User Interface Dictionary 



abbreviating-output (&optional stream &key width height lozenge-returns newline- 
substitute show-abbreviation abbreviate-initial-whitespace) &body body Function 

Binds local environment such that character output is abbreviated. That is, output 
exceeding a specified width or height (in characters) is truncated. 

stream The output stream; the default is *standard-output*. 

rwidth Specifiesthewidthincharactersbeyondwhichabbreviationoccurs, 

or t or nil. If nil, the default, individual lines are not truncated. If 
t, the width used is the value returned by the stream's :size-in- 
characters. 

rheight Specifiestheheight,inlines,beyondwhichabbreviationoccurs,ort 

or nil. If nil, the default, no truncation occurs. If t, the height used 
is the value returned by the stream's :size-in-characters. 

rlozenge-returns 

Boolean option specifying whether #\return characters at line trun- 
cations are displayed within a lozenge, rather than causing a new- 
line; the default is nil. 

mewline-substitute 

This is a generalization of rlozenge-returns. When given a string 
value, line truncations are displayed with that string, rather than 
causing a newline; the default is nil. 

rshow-abbreviation 

Boolean option specifying whether an ellipsis (...) is displayed 
where output truncation occurs. The default is nil, meaning that 
there is no explicit indication that truncation has occurred. 

You can also specify a string as an argument to : show-abbreviation. If you 
specify a string, the string appears after the abbreviation instead of 
ellipsis (...). 

rabbreviate-initial-whitespace 

Boolean option specifying that initial whitespace (spaces, tabs, new- 
lines) be suppressed; the default is nil. 

Example: 
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(defun abbrev-test (width height lozenge-p) 

(abbreviating-output (() :width width :height height 

: lozenge-returns lozenge-p 
: show-abbreviation t) 
(loop for row from 1 to 20 do 
(terpri) 

(loop for col from 1 to 100 do 
(format T " ~d:~d" row col))))) 

(abbrev-test 42 10 nil) 

The body code continues to run normally to completion, even though its output to 
stream may be truncated. 

Within abbreviating-output, the : set-cur sorpos operation is restricted. Only the x 
position may be specified, and then, only in characters. 

For an overview of abbreviating-output and related facilities, see the section 
"Controlling Line Output". 



tv:abstract-dynamic-item-list-mixin Flavor 

This is a noninstantiable mixin flavor that implements the general notion of dy- 
namically changing the item list. It causes the menu's item list to be updated at 
appropriate times. The actual item list is computed via the :update-item-list mes- 
sage. 



accept 

presentation-type &key (stream *query-io*) (prompt renter-type) (prompt-mode 
mornial) (original-type dwrpresentation-typej activation-chars additional-activation- 
chars blip-chars additional-blip-chars (inherit-context t) (default t ) (provide-default 
'dw::unless-default-is-nil) (default-type dw::original-type) (display-default 
dw::prompt) present-default history (prompts-in-line dw::*accept-active*) (initially- 
display-possibilities nil) input-sensitizer (handler-type #'dw::presentation- type-find- 
parser) query-identifier (separate-inferior-queries nil) (confirm nil) Function 

Reads printed representation of a Lisp object from a stream. If the representation 
is entered via a mouse gesture, it returns the object; if the representation is en- 
tered as a series of keyboard characters, it parses the series and returns the ob- 
ject. 

presentation-type 

Presentation type of the object to be accepted. 

rstream Specifies stream from which object is read; the default is 
*query-io*. 
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rprompt Specifies characteristics of the input prompt. (See the section "Dis- 
playing Prompts in the Input Editor".) Allowable values for this op- 
tion are: 

nil No prompt is printed. 

string String to be used as prompt. 

function Function to display a prompt string. It must take two po- 
sitional arguments. The first is the stream on which the 
prompt is to be displayed. The second is a keyword indi- 
cating the origin of the function call; for available key- 
words and related information, see the section "Displaying 
Prompts in the Input Editor". 

You typically provide a prompt function when you want 
the prompt to change dynamically. In such cases, you can 
ignore the second argument. 

Note: If there is no distinguishing default prompt for 
them, you should specify either a prompt or a query- 
identifier for each accept form within a dwraccep ting- 
values form; otherwise, there will be no way that the ac- 
cept-variable-values stream can identify which accept 
form is being run. 

list A list of a format string and format arguments, for exam- 

ple, where somewhere previously i and j have been set to 
5 and 3: 

(accept 'string 

:prompt '("Enter a string with ~D 
letters, ~D of them vowels" , i , j)) 
=> Enter a string with 5 letters, 
3 of them vowels: 

renter-type 

Causes the prompt "Enter a <presentation type>" to be 
used. The presentation type is that specified by the pre- 
sentation-type argument to accept. 

If rprompt is not nil, the default, if any, is displayed automatically 
after the prompt string. For example, a prompt string of "to file" 
for a presentation type of pathname is displayed as "to file (default 
Q:>foo.bar):". See the section "rdisplay-default Option to accept". If 
you provide a prompt string, whether accept provides trailing punc- 
tuation is determined by the "rprompt-mode Option to accept". 

rprompt-mode 

Specifies whether a colon and space is appended to a user-supplied 
prompt. A value of mormal causes a trailing colon and space to be 
appended; a value of rraw does not. This option also controls the 
parenthesizing in recursive calls to accept. 
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:original-type 

The original type supplied, to be passed through in successive re- 
cursive calls to present (or present-to-string or accept). 

: activation-chars 

Takes a list of characters that are used as activation characters for 
the duration of the call to accept. The default activators are #\re- 
turn and #\end. 

Activation characters signal the end of user input to the accept 
function. If input to the function is via the keyboard, the user must 
necessarily press an activation character to activate the accept. 

If input is via a translating mouse handler, defined by define- 
presentation-to-command-translator or define-presentation- 
translator, then whether an activation character is necessary de- 
pends on whether the translator returns an : activate t keyword- 
value pair. See the function define-presentation-translator. 

:additional-activation-chars 

Similar to : activation-chars; the list of characters supplied is added 
to the list of activators. Additional activation characters may be 
useful for activating accept when called recursively. 

:blip-chars 

Takes a list of characters that serve as delimiters of input fields for 
the duration of the call to accept. 

:additional-blip-chars 

Similar to :blip-chars; the list of characters supplied is added to 
the list of delimiters. Additional blip characters may be useful for 
terminating input fields when accept is called recursively. 

rinherit-context 

Boolean option specifying whether the current invocation of accept 
inherits the existing input context or establishes a new root node; 
the default value is t. This option is useful for controlling the input 
contexts at different levels in a recursive call to accept. 

rdefault Specifies the object to be used as the default value for this accept. 
If no object is specified by this option — and a default is to be 
given (see the rprovide-default option) — then the object offered is 
the one at the top of the presentation history for the presentation 
type specified in the presentation-type argument. 

rprovide-default 

Specifies whether to provide a default value for this accept. The de- 
fault is 'dw::unless-default-is-nil. If no value is supplied for this 
option, a default value is given unless it is nil. If nil is a valid de- 
fault that you want to be provided, then you must specify rprovide- 
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default t. 

: default-type 

Specifies the presentation type of the object offered as the default 
for completing the call to accept. The default for this option is 
dw::original-type, which in turns defaults to the type given by the 
presentation-type argument. 

This option is used for specifying explicitly the presentation type of 
the default when accepting compound presentation types created 
with the or presentation type. The value supplied should be one of 
the cases listed in the or or an even more specific (sub)type of one 
of these. This allows the default to be presented properly. See the 
presentation type or. 

rdisplay-default 

Controls the display of the default object. A value of t causes the 
default to be displayed whether or not a prompt is displayed; nil 
suppresses the display of the default whether or not a prompt is 
displayed. 

The default value for this option, dw::prompt, causes the default to 
be displayed when a prompt is displayed, and the default display to 
be suppressed when a prompt is not displayed. 

rpresent-default 

Boolean option specifying whether the default object is presented 
and accepted. This option is for the internal use of dwraccepting- 
values and related facilities. 

rhistory Specifies which presentation-type history to use for yanking purpos- 
es. A value of nil, the default, causes the history of the type speci- 
fied by the presentation-type argument to be used. 

Aside from providing another presentation type, you may also supply 
as the value to this option a history object. This would be appropri- 
ate if you constructed the presentation-type history yourself, rather 
than letting the presentation substrate do it for you. 

:prompts-in-line 

Boolean option specifying whether prompt is displayed in-line with 
parentheses or with a trailing colon. The default is t if the accept 
was called recursively, nil otherwise. 

rinitially-display-possibilities 

Boolean option specifying whether to display the objects that could 
be used as input in the current context; the default is nil. If t, the 
possibilities are presented before the prompt appears. This is the 
same list of possibilities that is displayed when the user presses 
HELP after the initial prompt appears. Note that this option only 
works reliably if there is a specific enumeration set of possibilities. 
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rinput-sensitizer 

This option is used internally by dw: accepting- values and related 
facilities. 

:handler-type 

This option is used internally by dw: accepting- values and related 
facilities. 

: query-identifier 

Specifies a unique identifier for this call to accept; the default is 
derived from the prompt. 

This option is used when the accept is used within an 
dw: accepting- values form and the prompt is not unique. 

If the queries do not have unique prompts, use the : query-identifier 
option to accept to distinguish them. Identity will be based on 
equal. Examples: 

Wrong: 

(dwiaccepting-values () 
(loop for i from 1 to 10 

collect (accept 'integer))) 

Right: 

(dwiaccepting-values () 
(loop for i from 1 to 10 

collect (accept 'integer 
: prompt 
(format nil "Number #~D" i)))) 

or 

(dw:accepting-values () 
(loop for i from 1 to 10 
col lect 

(accept 'integer 

:query-identif ier i))) 

also (valid case for same prompts) 

(dw:accepting-values () 
(loop for i from 1 to 5 

collect (let ((num (accept 'integer 
: prompt 

(format nil "Number #~D" i)))) 
(1 ist num 

(when (oddp num) 
(accept 'boolean 
:query-identif ier 
(list :subfield i) 
: prompt 
" Subfield for that")))))) 
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See the function dwraccepting-values. 

rseparate-inferior-queries 

Boolean option specifying whether recursive calls to accept go on separate lines 
when executing an dwraccepting-values function; the default is nil. 

rconfirm 

Specifies, when set to t, that the user must confirm input before it will be accept- 
ed. The default is nil. This option is ignored unless the call to accept is made 
from the Command Processor (CP). 

For an overview of accept and related facilities: See the section "Using Presenta- 
tion Types for Input". 



accept-from-string presentation-type string &rest args &key index (start 0) end &al- 
low-other-keys Function 

Reads the printed representation of a Lisp object from a string and returns the ob- 
ject with a specified presentation type. This function is the presentation- system 
equivalent of the Common Lisp function read-from-string. 

presentation-type 

Presentation type of the object to be accepted. 

string String from which to accept the object. 

args Keyword options to accept. 

rstart Specifies the position of the first character to be parsed. The de- 
fault is 0, the position of the first character. 

rend Specifies the position of the first character not to include in the 

parsing of the string. 

Examples: 

(accept-from-string 'string "Test 1") ==> 

"Test 1" 

STRING 

(accept-from-string 'integer "Test 2" :start 5) ==> 

2 

INTEGER 

For an overview of accept-from-string and related facilities: See the section "Us- 
ing Presentation Types for Input". 



dwr accept- values descriptions &key (prompt nil) (near-mode '(rmouse)) (stream 
*query-io*) (own-window nil) (temporary-p dwr rown- window) (initially-select-query- 
identifier nil) Function 



Page 1 135 



Reads a series of printed representations of Lisp objects from a stream and re- 
turns one value for each object read. The objects may be entered via mouse ges- 
tures or as keyboard input. 

descriptions 

List of descriptions. Each description is a list of a presentation type 
and a set of the keyword options; available keywords are those al- 
lowed by accept, being returned for all occurrences of that type. 

Example: 

(dw:accept-values '((integer :prompt "Half-life" 

: default 24000) 
(pathname :prompt "Log file") 
(integer :prompt "Session number")) 
:prompt "Atomic experiment") 

rprompt Specifies a string, or a function returning a string, serving as the 
prompt or heading for the whole series of input prompts that follow. 

:near-mode 

Specifies where the menu appears. The default makes it appear 
near the position of the mouse cursor at the time the function is 
called. For other possibilities: See the method (flavorrmethod 
:expose-near tv:essential-set-edges) . 

This option is applicable only when the value of the :own-window 
option is t. 

rstream Specifies the stream to be used for input and output; the default is 
*query-io*. 

:own-window 

Specifies whether the input/output interaction occurs in a separate, 
momentary window or runs "in place" in the current window like 
ordinary input/output; the default is nil. 

:temporary-p 

Boolean specifying whether the menu window is temporary, that is, 
whether the menu locks the underlying window without graying it 
out. If the value of the :own-window option is t, then the default 
for this option is t, a temporary window; if the value of :own- 
window is nil, this option is inapplicable. 

:initially-select-query-identifier 

Specifies that a particular field is preselected when the user inter- 
action begins. The field to be selected is tagged by the rquery- 
identifier option to accept, passed through to accept by dwraccept- 
values. Use this tag as the value for the :initially-select-query- 
identifier keyword, as shown in the following example: 
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(dw: accept-values '((integer 



(boolean 



prompt "Number of times" 
query-identifier fred) 
prompt "Backwards")) 



: initial ly-select-query-identif ier 'fred) 

When the initial display is output, the mouse cursor appears after 
the prompt of the tagged field, just as if the user had selected that 
field by clicking on it. The default value,if any, for the selected 
field is not displayed. 

For an overview of dw: accept- values and related facilities: See the section "Using 
Presentation Types for Input". 



dw:accept-values-choose-from-sequence stream sequence value query-identifier 
&key (type 't) highlighted-type printer (key #'identity) (highlighting-test #'eq) high- 
lighting-function (select-action #'(lambda (dw::new ignore) dw::new)J fill-p multi- 
ple-choices (single-box t) Function 

The function to use when writing a rchoose-displayer in defining a presentation 
type. Here is an example from an internal presentation-type definition for dwralist- 
subset: 

:choose-displayer 

((stream object query-identifier &key original-type) 
(dw : accept-val ues-choose-f rom-sequence 
stream alist object query-identifier 
:type original -type 
:mul tiple-choices t 
:highl ighting-test ft' (lambda (e list) 

(member e list :test highlighting-test)) 
:printer ft' (lambda (element stream) 

(princ (token-element-string element) stream)) 
: key # ' tv : menu-execute-no-si de-effects 
: select-action ft' (lambda (new list) 



(if (member new 1 ist 
(remove new 1 ist 
(adjoin new list 



test highlighting-test) 
test highlighting-test) 
test highlighting-test))))) 



stream The stream on which to display the accept-values menu. 

sequence The sequence from which to choose a value. 

value The current value of the query. Normally, this is the object argu- 
ment to the rchoose-displayer function, value is used as an argu- 
ment to the :highlighting-test function. 

query-identifier 

Specifies a unique identifier for this accept-values call. 

rtype The presentation type of the object to be accepted. 
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:highlighted-type 

Presentation type of choice(s) to highlight. 

rprinter Specifies a function of two arguments, the object and a stream, to 
use to print the menu choices. 

:key Specifies a function to obtain the value of a selected item from an 

element of sequence. The default is #'identity. 

:highlighting-test 

Specifies a function that determines which value derived from se- 
quence by :key is a currently selected choice, and therefore should 
be highlighted. The first argument is the value derived from se- 
quence, the second argument is the current value of the query, ini- 
tially value. The default is (function eq). The function in the exam- 
ple above allows more than one choice to be selected, by interpret- 
ing value as a list of selected choices. 

rhighlighting-function 

Specifies a function to be used to highlight the choices. 
rhighlighting-function gets called with continuation &rest continua- 
tion-args where the continuation-args are choice, stream, and type. 
The default if rhighlighting-function is unspecified or nil is to 
present the choice in boldface. 

rselect-action 

The function to execute when an item is selected. It takes two ar- 
guments, the value of the selected item and the current value of 
the query, initially value. The value it returns is the new value of 
the query. The default is a function that simply returns its first ar- 
gument. 

rfill-p Boolean specifying when t that the line on which the choices are 
displayed should be filled, that is, displayed with newline characters 
to prevent wrapping of output for long lines. 

rmultiple-choices 

Boolean specifying when t that more than one choice can be accept- 
ed. 

r single-box 

Boolean specifying when t, the default, that the mouse-sensitivity of 
objects output by this form be highlighted by a single box. 



dwr accept- values-command-button f&optional (stream '*standard-output*)J 

prompt &body conditional-forms Function 

Used within dwr accepting- values form, displays prompt on stream and creates an 
area, the "button," in which when a mouse button is clicked the conditional-forms 
are evaluated. 

Example: 
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(defun pathname-test () 
(let ((number 10) 

(pathname #P"foo.bar")) 
(dw:accepting-values () 

(dw:accept-values-f ixed-1 ine "Here are some questions:") 
(dw : accept-val ues-command-button () 

(write-string "Click here to synchronize version.") 
(setq pathname (send pathname : new-version number))) 
(terpri) 

(list (setq number (accept 'integer :prompt "Version" 

:default number)) 
(setq pathname (accept 'pathname :prompt "File" 

: default pathname)))))) 



dw:accept-values-display-exit-boxes &key (stream *query-io*J (level rtop-levelj 

Function 

Used within dw: accepting- values form, displays the mouse-sensitive exit boxes 
"RBORT aborts, END uses these values" on stream. 



dw: accept- values-fixed-line string &optional (stream *query-io*J Function 

Used within a dw: accepting- values form, displays string on stream. 

dw:accept-values-for-defaults continuation Function 

Runs continuation with a stream argument, causing calls to accept to return their 
defaults. This is like the user encountering dw: accepting- values and pressing END 
right away. 

dw: accept- values-into-list descriptions &key .-prompt (mear-mode '(:mouse)J 
(: stream *query-io*J :own-window (:temporary-p dw::own- window) dnitially-select- 
query-identifier Function 

Performs the same operation as dw:accept-values, but returns a list rather than 
multiple values. See the function dw:accept-values. 



dw: accept- variable- values variables &key {prompt "Choose Variable Values") 
{near-mode '(:mouse)) {delayed t) {stream *query-io*) {own-window nil) 
{temporary-p dw::own- window) {initially-select-query-identifier nil) Function 

Provides a menu-like facility for setting the values of special variables to values 
provided by the user. The value for each variable is read via a call to accept us- 
ing a specified presentation type. 



Page 1 139 



(Usage note: dw: accept- variable- values is intended for use with special variables, 
not local ones. As such, it is useful for conversion from tvrchoose-variable-values 
but is, in general, less appropriate for new applications of accept-values technology. 
For the latter, we recommend using dw: accept-values and dwraccepting-values.) 

variables A list of variable descriptions. Each description is a list of the form 

(place &optional (prompt : enter-type) (type 'sys: expression)) 

where place is usually a variable name; prompt is either a prompt 
string, renter-type (the default), or a function for returning a 
prompt string; and type is the presentation type of the variable 
(sysrexpression by default). 

Example: 

(dw : accept-vari abl e-val ues 

'((*a* "Number" integer) 
(xbx "File" pathname) 
(xcx "Printer" sys:printer))) ==> 

Choose Variable Values 
Number: an integer 
File: the pathname of a file 
Printer: a printer 

aborts, uses these values 
NIL 

rprompt Specifies a string, or a function returning a string, serving as the 
prompt or heading for the whole series of input prompts that follow. 

:near-mode 

Specifies where the menu appears. The default makes it appear 
near the position of the mouse cursor at the time the function is 
called. For other possibilities: See the method (flavorrmethod 
:expose-near tv:essential-set-edges) . 

This option is applicable only when the value of the :own-window 
option is t. 

rdelayed Boolean option specifying whether variables are updated with user- 
supplied values after the entire accept-variable-values interaction is 
complete, or individually after input to each variable field is termi- 
nated; the default is t. 

rstream Specifies the stream to be used for input and output; the default is 
*query-io*. 

:own-window 

Specifies whether the input/output interaction occurs in a separate, 
momentary window or runs "in place" in the current window like 
ordinary input/output; the default is nil. 
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:temporary-p 

Boolean specifying whether the menu window is temporary, that is, 
whether the menu locks the underlying window without graying it 
out. If the value of the :own-window option is t, then the default 
for this option is t, a temporary window; if the value of :own- 
window is nil, this option is inapplicable. 

:initially-select-query-identifier 

Specifies that a particular field is pre-selected when the user inter- 
action begins. The field to be selected is tagged by the rquery- 
identifier option to accept; use this tag as the value for the 
:initially-select-query-identifier keyword, as shown in the following 
example: 

(dw : accept-vari abl e-val ues 
'(( a "The file" 'pathname) 
( b "The number" 'integer) 
( c "The printer" 'sys:printer)) 

: initial ly-select-query-identif ier 'the- tag) 

When the initial display is output, the mouse cursor appears after 
the prompt of the tagged field, just as if the user had selected that 
field by clicking on it. The default value, if any, for the selected 
field is not displayed. 

For an overview of dw: accept- variable- values and related facilities: See the sec- 
tion "Using Presentation Types for Input". 



dw: accepting- values f&optional (stream '*query-io*J &key :own-window Odisplay- 
exit-boxes (not dw::own- window),) (:temporary-p dw::own- window) (.'label "Multiple 
accept",) (:near-mode '(:mouse)J :initially-select-query-identifier :resynchronize-every- 
pass : queries-are-independent (xhanged-value-overrides-default t) (: query-entry-mode 
•Avlme)) &body body Function 

Causes all calls to accept within body to appear in a single, dw: accept- variable- 
values-like menu that can be modified dynamically. If this macro is called from a 
remote terminal or some other device that does not support menus, it just per- 
forms successive calls to accept. 

stream Stream for input and output; the default is *query-io*. 

If the body of an accepting-values form assigns the returned value to a variable, 
as, for example, with 

(setq a (accept . . . )) 

and the user never submits any new input for this call to accept, that variable 
gets set to the default value of the accept. 
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:own-window 

Specifies whether the input/output interaction occurs in a separate, 
momentary window or runs "in place" in the current window like 
ordinary input/output; the default is nil. 

: display-exit-boxes 

Boolean option specifying whether the Abort-End exit message is 
displayed. The default is to display it unless the interaction is in its 
own window (see the :own-window option). 

:temporary-p 

Boolean specifying whether the menu window is temporary, that is, 
whether the menu locks the underlying window without graying it 
out. If the value of the :own-window option is t, then the default 
for this option is t, a temporary window; if the value of :own- 
window is nil, this option is inapplicable. 

rlabel Specifies a string to serve as the title of the interaction menu. This 
option is applicable only if the value of the :own-window option is 
t. 

:near-mode 

Specifies where the menu appears. The default makes it appear 
near the position of the mouse cursor at the time the function is 
called. For other possibilities: See the method (flavorrmethod 
:expose-near tv:essential-set-edges) . 

This option is applicable only when the value of the :own-window 
option is t. 

:initially-select-query-identifier 

Specifies that a particular field is pre-selected when the user inter- 
action begins. The field to be selected is tagged by the rquery- 
identifier option to accept; use this tag as the value for the 
:initially-select-query-identifier keyword, as shown in the following 
example: 

(let (a b c) 

(dwiaccepting-values (xquery-iox 

: initial ly-select-query-identif ier 'the- tag) 
(setq a (accept 'pathname :prompt "The file")) 
(setq b (accept 'integer :prompt "The number" 

:query-identif ier 'the-tag)) 
(setq c (accept 'sys:printer 

:prompt "The printer"))) 
(format t "Printing ~D copies of 

file ~A on ~A" b a c)) 

When the initial display is output, the mouse cursor appears after 
the prompt of the tagged field, just as if the user had selected that 
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field by clicking on it. The default value, if any, for the selected 
field is not displayed. Note: you must specify either a unique 
prompt or a query-identifier for each accept form within an 
dw: accepting- values form; otherwise, there will be no way that the 
accept-variable-values stream can identify which accept form is be- 
ing run. 

:resynchronize-every-pass 

Boolean option specifying whether earlier queries depend on later 
values; the default is nil. 

You can use this option to alter dynamically the multiple-accept 
display. The following is a simple example. It initially displays an 
integer field that disappears if a value other than 1 is entered; in 
its place a two-field display appears. 

(defun alter-multi pie-accept () 
(f resh-1 ine) 
(let ((flag 1)) 

(dw : accepti ng-val ues 

(t : resynchronize-every-pass t) 
(if (= flag 1) 

(setq flag (accept 'integer : default flag)) 
(accept 'string) 
(accept 'pathname))))) 

As the example shows, to use this option effectively, the controlling 
variable(s) must be initialized outside the lexical scope of the 
dw: accepting- values macro. 

body The body is run in order to generate the initial prompt/value dis- 

play. The body (or some part of it) is re-run each time a change is 
made; so the dependencies that later calls to accept may have on 
earlier ones will be correctly resolved. Because the body is run re- 
peatedly, you must be careful of side-effects in the body code. Also, 
because the stream carries the state information, all input/output 
calls within the body must use the stream specified in the 
dw: accepting- values options list. 

If you had a file \l : >RJ>tst . dwg and a printer named Audubon, you 
could do something like the following. (Supply a pathname at your 
site and a local printer to try these examples.) 

Good examples: 
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(let ((a #P"\/:>RJ>TST.DWG") 
(b 2) 

(c (net: find-object-named :printer "audubon"))) 
(dw:accepting-values (xquery-iox 

: prompt "Good Example") 
(setq a (accept 'pathname 

: prompt "The file" 
: default a)) 
(setq b (accept 'integer 

:prompt "The number" :default b)) 
(setq c (accept 'sys:printer 

:prompt "The printer" 
: default c))) 
(format t "Printing ~D copies of 

file ~A on ~A" b a c)) 

(multiple-value-bind (a b c) 
(dw:accepting-values () 
(values 
(accept 'pathname :prompt "The file") 
(accept 'integer :prompt "The number") 
(accept 'sys:printer 

:prompt "The printer"))) 
(format t "Printing ~D copies of 

file ~A on ~A" b a c)) 

Poor example: 

(let ((the-list nil)) 
(dw:accepting-values () 
(push 
(list 

(accept 'pathname :prompt "The file") 
(accept 'sys:printer :prompt "The printer")) 
the-list)) 
(format t "The list = ~S" the-list)) 

The above example is a poor one because the output list will have 
an unpredictable number of elements; this detracts from its useful- 
ness. 

A useful presentation type to use with accept functions in the body of a 
dw: accepting- values macro is alist-member. Its usefulness derives from the key- 
word options available for inclusion in the item lists contributing to the alists. 
Three options exist: : documentation, rstyle, and :selected-style. 

The value of the : documentation keyword is a string that appears in the mouse 
documentation line when the mouse cursor is over the item (that is, the item is 
highlighted). 
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rstyle specifies the character style for the item when it is displayed, rselected- 
style specifies the character style of the item when it is selected, that is, after it 
has been clicked on. The :selected-style defaults to the boldface version of the un- 
selected style. 

Use of the alist-member presentation type with dw: accepting- values is illustrated 
by the following example: 



(defun filter-a-v () 
(let ((low-pass-list 

'(("Mean" :value :mean 

: documentation "1 1 1 mask" 
: style (: swiss : roman : normal) 
: selected-style (:dutch :bold nil)) 
("Gaussian" :value :gauss 
: documentation "1 2 1 mask" 
: style (: swiss : roman : normal) 
: selected-style (:dutch :bold nil)))) 
(edge-1 ist 

'(("Laplacian, HP" :value :lpl-hp 
: documentation "-1 3 -1 mask" 
: style (: swiss : roman : normal) 
: selected-style (:dutch :bold nil)) 
("Laplacian, ED" :value :lpl-ed 
: documentation "-1 2 -1 mask" 
: style (: swiss : roman : normal) 
: selected-style (:dutch :bold nil))))) 
(dw:accepting-values (xquery-iox : own-window t) 
(f resh-1 ine) 
(setq lo-pass-f (accept '((alist-member 

:alist , low-pass-1 ist) 
:description "a low-pass filter"))) 
(setq edge-f (accept '((alist-member 

:alist , edge-1 ist) 

:description "a hi-pass/edge filter")))))) 



For an overview of dw: accepting- values and related facilities: See the section "Us- 
ing Presentation Types for Input". 

For additional examples, see the file sys:examples;accepting-values.l isp 



(flavorrmethod :activate-p tvressential-window) t-or-nil 



Init Option 



If this option is specified non-nil, the window is activated after it is created. The 
default is to leave it deactivated. Note that :activate-p and :expose-p are argu- 
ments in init-options which cannot be specified in the flavor's :default-init-plist. 
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(flavorrmethod :activate-p tvrmenu) t-or-nil Init Option 

If this option is specified non-nil, the window is activated after it is created. The 
default is to leave it deactivated. 



ractivation function &rest arguments Option 

For each character typed, the input editor invokes function with the character as 
the first argument and arguments as the remaining arguments. If the function re- 
turns nil, the input editor processes the character as it normally would. Otherwise, 
the cursor is moved to the end of the input buffer, a rescan of the input is forced 
(if one is pending), and the blip (ractivation character numeric-arg) is returned by 
the final sending of the :any-tyi message to the stream. Activation characters are 
not inserted into the input buffer, nor are they echoed by the input editor. It is 
the responsibility of the reading function to do any echoing. For instance, 
zlrreadline, not the input editor, types a Newline at the end of the input buffer 
when RETURN, END, or LINE is pressed. 



(flavorrmethod :add-asynchronous-character sirinteractive-stream) character 
handler Method 

Defines a new asynchronous character for the stream, character is the character to 
be treated asynchronously and handler is the function to be called (with two argu- 
ments, character and self). It checks the types of the arguments. 

The standard handler that the system uses to intercept c-n-SUSPEND, c-RBORT, and 
so on, is the function tvrkbd-asynchronous-intercept-character . Therefore, if you 
have, for example, removed one of these system asynchronous characters, you can 
restore it through: 

(send stream :add-asynchronous-character character 
' tv : kbd-asynchronous-i ntercept-character) 



cpradd-command-accelerator command-table function-name characters Function 

Adds a keyboard accelerator for an existing command named function-name in the 
table command-table. The list characters includes every character that will invoke 
the command. See the function cprdefine-command-accelerator. 



tv:add-f unction-key char function documentation &rest options Function 

Adds char to the list of keys that can follow the FUNCTION key. Following is an ex- 
planation of the arguments: 

char The character that should be typed after FUNCTION to get the 

new command. Lowercase letters are converted to uppercase. 

function A specification for the action to be taken when the user press- 

es FUNCTION char, function can be a symbol or a list: 
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Symbol: The name of a function to be applied to one argu- 
ment. The argument is the numeric argument to FUNCTION 
char (an integer) or nil if the user supplied none. 



documentation 



• List: A form to be evaluated. 

function is applied or evaluated in a newly created process un- 
less you supply the rkeyboard-process option (see below). 

A form to be evaluated when the user presses FUNCTION HELP 
to produce documentation for the command. The form should 
return a string, a list of strings, or nil (of course, documenta- 
tion can just be a string or nil): 



String: One line of text describing this command for FUNC- 
TION HELP. 

List of strings: Each string is a line of text for 
FUNCTION HELP to print successively in describing this com- 
mand. (Note: you can accomplish the same effect by using a 
single string containing NEWLINE characters.) Usually docu- 
mentation is a Lisp form that looks like '("line 1" "line 2" 
...). 



options 



• nil 

FUNCTION HELP prints nothing describing this command. 

A series of keywords sometimes followed by values. Possible op- 
tions are rkeyboard-process, :process-name, rprocess, and 
rtypeahead: 



rkeyboard-process 

function is applied or evaluated in the keyboard process in- 
stead of a newly created process. This option exists because 
certain built-in commands must run in the keyboard process. 
You should not use this option for new commands. The cost 
of creating a new process is quite low. 



:process-name string 

string is the name of the newly created process in which 
function is applied or evaluated. If you don't supply this op- 
tion or the rprocess option, the name of the process is 
"Function Key". 

rprocess list 

list is a list to be used as the first argument to process- 
run-function, called to create a new process in which func- 
tion is applied or evaluated. This option takes precedence 
over rprocess-name. 
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• rtypeahead 

Everything the user types before pressing the FUNCTION key 
is treated as typeahead to the currently selected window. 
Use this option with commands that change windows to en- 
sure that the user's typed input goes to the I/O buffer of the 
expected window. 

Here is an example of a call to tv:add-function-key: 

(tv:add-f unction-key #\refresh 'tv:kbd-screen-redi splay 

"Clear and redisplay all windows.") 

See the variable tv:*f unction-keys*. 

(flavorrmethod :add-highlighted-item tvrmenu-highlighting-mixin) item Method 
Add an item to the list of items to be highlighted. 

(flavorrmethod :add-highlighted- value tvrmenu-highlighting-mixin) value Method 

Adds an item to the list of items to be highlighted. Refers to the item by value. 
For instance, if your item-list is an association list, with elements {string . 
symbol), this message uses symbol. This only works for menu items that can be ex- 
ecuted without side-effects, not, for example, the reval and rfuncall kinds.See the 
section "tvrmultiple-menu-mixin Messages". 

tv:add-select-key char flavor name &optional (create-p t) clobber-p Function 

Adds char to the list of keys that can follow the SELECT key. Following is an expla- 
nation of the arguments: 

char The character (character object) that should be typed after SE- 

LECT to get the new command. Lower-case characters are con- 
verted to upper case. Number keys are not permitted. 

flavor A specification for the window to be selected when the user 

presses SELECT char, flavor can be a symbol, an instance, or a 
list: 

• Symbol: The name of a flavor. The SELECT command search- 
es the list of previously selected windows and selects a win- 
dow of flavor flavor if it finds one. (flavor can be the name 
of a component flavor of the window, not just the instantiat- 
ed flavor.) Otherwise, if the currently selected window is of 
flavor flavor, it beeps. Otherwise, it takes the actions speci- 
fied by create-p. 

• Instance: A window. The SELECT command selects that win- 
dow. 
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name 



create-p 



• List: A form to be evaluated (in the SELECT command's new- 
ly created process). The form should return a window to be 
selected or a symbol that is the name of a flavor of window 
to be selected. 

A string giving the colloquial name of the program to be se- 
lected, name is printed by SELECT HELP. 

A specification for actions that the SELECT command should 
take if it cannot find a previously selected window of flavor 
flavor and if the currently selected window is not of flavor fla- 
vor, create-p can be nil, t, another symbol, or a list: 



• nil: Beeps. 

• t: Calls tvrmake-window with no options to create a window 
of flavor flavor. Selects that window. 

• Another symbol: The name of a flavor. Calls tvrmake- 
window with no options to create a window of flavor 
create-p. Selects that window. 

flavor and create-p can be names of different flavors. For ex- 
ample, flavor might be the name of a mixin that is a compo- 
nent of several flavors, all of which are suitable flavors of 
window to select. 



clobber-p 



• List: A form to be evaluated (in the SELECT command's new- 
ly created process). The form presumably selects a window. 

Boolean option specifying whether to reassign a key to select a 
new program without first requesting confirmation; a value of 
t suppresses the confirmation prompt. 



If the user presses char with the c- modifier (after pressing SELECT), and if flavor 
is a symbol that names a flavor or is a form that returns the name of a flavor, the 
SELECT command does not search for previously selected windows of flavor flavor. 
Instead, it takes the actions specified by create-p. But if flavor is a window, the 
SELECT command selects that window even if the user presses char with the c- 
modifier. 



Here is an example of a call to tv:add-select-key: 

(tv:add-select-key #/E 'zwei :zmacs-f rame "Editor" 



: clobber-p nil) 



As of Genera 7.3 Ivory, the variable tv:*select-keys*, previously used by the SE- 
LECT key, is obsolete, it is retained for compatibility. (The SELECT key now uses an 
internal database.) Use tv:add-select-key where possible. 
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dw:add-standard-menu-accelerator command-table command-symbol &optional ac- 
celerator-name (menu-level '(:top-level)J Function 

Defines normal command menu actions. This is what the define-program- 
command :menu-accelerator option expands into. Use this to add items to the 
command menu if you do not use :menu-accelerator t or to add synonyms. 

For an overview of this and related topics: See the section "How Command Menus 
Work". 



tv:add-to-system-menu-create-menu name flavor documentation &optional after 

Function 

Adds an entry to the menu that appears when you click on [Create] in the System 
menu or in the Edit Screen menu, name is a string, the name of the menu item. 
flavor, a flavor name, is the flavor of window that is created when the menu item 
is selected, documentation is mouse documentation for the menu item, after deter- 
mines where in the [Create] menu the item should appear: 

nil Bottom of the menu 

t Top of the menu 

string After the item named string that is now in the menu 

Example: 

(tv : add-to-system-menu-create-menu 
"Concept Editor" 'crl : concept-editor 
"Edit the representation of a concept in the CRL system") 



tv:add-to-system-menu-programs-column name form documentation &optional af- 
ter Function 

Adds a program to the Programs column of the System menu, name is a string, 
the name to appear in the menu, form is a form to evaluate, in its own process, 
when the program is selected; often this is a call to tv:select-or-create-window-of- 
flavor. documentation is mouse documentation for the menu item, after determines 
the position of the new program name in the Programs column: 

nil Bottom of the column 

t Top of the column 

string After the program named string that is now in the menu 

Example: 

(tv : add-to-system-menu-programs-col umn 
"Concept Editor" 'crl :concept-editor 
"Edit the representation of a concept in the CRL system") 
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tv:add-typeout-item-type Function 

The following special form is used to declare information about a mouse-sensitive 
type by adding an entry to an alist kept in a special variable. 

(tv : add-typeout-i tern-type 

alist type name operation default-p documentation) 

This alist can be put into the item-type alist of a mouse-sensitive window, using, 
for instance, the :item-type-alist init-plist option. Note that each possible operation 
on a particular mouse-sensitive item type is defined with a separate tvradd- 
typeout-item-type form; this allows each operation to be defined at the place in 
the program where it is implemented, rather than collecting all the operations into 
a separate table. It also allows new operations to be added in a modular fashion. 

alist is the special variable that contains the alist. You should declare it nil with 
defvar before defining the first item type. Each program that uses mouse-sensitive 
items has its own alist of item types, so that there is no conflict in the names of 
the types. 

type is the keyword symbol for the type being defined. 

name is the string that names the operation. 

operation is the action to be taken, for instance, the function to be called. 

default-p is optional; if it is supplied and non-nil, it means that this operation is 
the default performed when you click the left button on an item of this type. 

documentation is optional but highly recommended; it is a string that documents 
what operation does. When the user points the mouse at an item of this type, the 
documentation line at the bottom of the screen displays the documentation for the 
default operation (reachable by the left button) and a list of the operations in the 
menu (reachable by the right button). If the user clicks right, calling for a menu, 
then the screen displays documentation for the operation pointed at. 

alist, type, and operation are not evaluated, name, default-p, and documentation are 
evaluated. 

When operation is a function, the tv:add-typeout-item-type form is typically 
placed near the definition of the function in the program source file. 



(flavorrmethod :adjust-geometry-for-new-variables tvrchoose-variable-values- 
window) width Method 

The variable width is specified as nil if the size is not to be adjusted, otherwise 
the inside-width and height are also adjusted. The :adjust-geometry-for-new- 
variables message is normally sent after sending a rsetup message. (It is not nec- 
essary to send it after a : set- variables message.) 



:alias-for-selected-windows Message 
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When the :alias-for-selected-windows message is sent to a window, it returns the 
representative window of the receiver's activity. If two windows have the same 
alias-for-selected-windows, they belong to the same activity. 

This message is sent by both the system and the user and may be received by ei- 
ther, although usually the system-supplied methods suffice. The default method (of 
tvrsheet) returns the window to which the message is sent, declaring the window 
to be in an activity by itself. tv:select-relative-mixin supplies a method that re- 
turns the superior's alias, unless the window to which the message is sent is a 
top-level window (that is, its superior is a screen); in that case it returns the win- 
dow itself. tv:pane-mixin and tvrbasic-typeout-window supply methods that return 
the superior's alias. 



tv:*allow-pop-up-notifications* Variable 

If the value is t, asynchronous notifications not handled by the selected process 
will be displayed in a pop-up window. If the value is nil and the window does not 
handle asynchronous notifications, any notification will just be held and an alert 
will appear in the progress note area at the very bottom of the screen: "~D pending 
notifications". A user who sees this can switch to a Lisp listener or press SELECT 
N to see the notification. 

Note that whether an asynchronous notification is "handled" by a process depends 
on the process state and the activity in progress. Lisp Listeners, for example, are 
almost always prepared to handle notifications, by printing them at the current 
output point on the window, unless other unusual output is occurring. A Zwei- 
based application (Zmacs, Zmail, Converse) prints notifications in the mode-line 
window if it is in the User Input state and the message will fit in that window. 
Most other applications are not prepared to handle notifications. 



tv:alu-and Variable 

And alu function. Like tv:alu-seta, this is not useful with the drawing operations, 
but can be useful with the bitblt operations. 1 bits in the input leave the corre- 
sponding output bit alone, and bits in the input clear the corresponding output 
bit. 

This is the same as the Common Lisp boole-and function. 



tv:alu-andca Variable 

And-with-complement alu function. Bits in the object being drawn are turned off 
and other bits are left alone. This is the erase-aluf of most windows. It is useful 
for erasing areas of the window or for erasing particular characters or graphics. 

This is the same as the Common Lisp boole-andcl function. 

tv:alu-ior Variable 
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Inclusive-or alu function. Bits in the object being drawn are turned on and other 
bits are left alone. This is the char-aluf of most windows. If you draw several 
things with this alu function, they will write on top of each other, just as if you 
had used a pen on paper. 

This is the same as the Common Lisp boole-ior function. 



tv:alu-seta Variable 

Set all bits in the affected region. This is not useful with the drawing operations, 
because the exact size and shape of the affected region depend on the implementa- 
tion details of the microcode. The seta function is useful with the bitblt opera- 
tions, where it causes the source rectangle to be transferred to the destination 
rectangle with no dependency on the previous contents of the destination. 

This is the same as the Common Lisp boole-1 function. 



tv:alu-xor Variable 

Exclusive-or alu function. Bits in the object being drawn are complemented and 
other bits are left alone. Many graphics programs use this. The graphics messages 
take quite a bit of care to do "the right thing" when an exclusive-or alu function is 
used, drawing each point exactly once and including or excluding boundary points 
so that adjacent objects fit together nicely. The useful thing about exclusive-or is 
that if you draw the same thing twice with this alu function, the window's con- 
tents are left just as they were when you started; so this is good for drawing ob- 
jects if you want to erase them afterwards. 

This is the same as the Common Lisp boole-xor function. 



(flavorrmethod :any-tyi sirinteractive-stream) &optional eof-action Method 

Reads and returns the next character or blip of input from the stream, waiting if 
there is none. Where the character comes from depends on the value of the vari- 
able sysrrubout-handler. Following is a summary of actions for each possible val- 
ue of sysrrubout-handler: 

nil If the input buffer contains unscanned input, take the next 

character from there. Otherwise, take the next character from 
the stream. 

rread If the input buffer contains unscanned input, take the next 

character from there. Otherwise, if an activation blip or char- 
acter is present, return that. Otherwise, enter the input editor. 

:tyi Take the next character from the stream. 

If eof-action is not nil, an error is signaled when an end-of-file is encountered. 
Otherwise, the method returns nil when an end-of-file is encountered. The default 
for eof-action is nil. 
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(flavorrmethod :any-tyi tv:stream-mixin) &optional eof-action Method 

Reads and returns the next character or blip of input from the window, waiting if 
there is none. Where the character comes from depends on the value of the vari- 
able sysrrubout-handler. Following is a summary of actions for each possible val- 
ue of sysrrubout-handler: 

nil If the input buffer contains unscanned input, takes the next 

character from there. Otherwise, takes the next character from 
the window's I/O buffer. 

rread If the input buffer contains unscanned input, takes the next 

character from there. Otherwise, if an activation blip or char- 
acter is present, returns that. Otherwise, enters the input edi- 
tor. 

:tyi Takes the next character from the window's I/O buffer. 

If eof-action is not nil, an error is signalled when an end-of-file is encountered. 
Otherwise, the method returns nil when an end-of-file is encountered. The default 
for eof-action is nil. 



(flavorrmethod :any-tyi-no-hang sirinteractive-stream) &optional eof-action 

Method 

Returns the next character from the stream if it is immediately available. If no 
characters are immediately available, returns nil. It is an error to call this method 
from inside the input editor (that is, if the value of sysrrubout-handler is not nil). 
eof-action is ignored. This is used by programs that continuously do something un- 
til a key is typed, then look at the key and decide what to do next. 



(flavorrmethod rany-tyi-no-hang tvrstream-mixin) &optional eof-action Method 

Checks the window's I/O buffer and returns the next character if it is immediately 
available. If no characters are immediately available, it returns nil. It is an error 
to call this method from inside the input editor (that is, if the value of 
sysrrubout-handler is not nil), eof-action is ignored. This is used by programs that 
continuously do something until a key is typed, then look at the key and decide 
what to do next. 



(flavorrmethod rappend-item tvrtext-scroll-window) new-item Method 

Inserts new-item after the last item in the list, new-item can be any Lisp object. 

If the last item in the list is visible in the window and there is room to display 
the new item, the window redisplays to show the new item. 



(flavorrmethod r appropriate- width tvrchoose-variable-values-window) &optional 
extra-space Method 
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This returns the inside-width appropriate for this window to accommodate the cur- 
rent set of variables and their current values. Send this message after a rsetup 
and before a rexpose, and use the result to send an radjust-geometry-for-new- 
variables message. The returned width is not larger than the maximum that fits 
inside the superior. 

If extra-space is supplied, it specifies the amount of extra space to leave after the 
current value of each variable of the kind that displays its current value (rather 
than a menu of all possible values). This extra space allows for changing the value 
to something bigger. The extra space is specified as either a number of characters 
or a character string. The default is to leave no extra space. 



(flavorrmethod : asynchronous-char acter-p sirinteractive-stream) character 

Method 

Returns non-null when character is an asynchronous character for this stream. 



(flavorrmethod : asynchronous-characters sirinteractive-stream) spec-list 

Init Option 

Specifies the asynchronous characters for the stream, spec-list is a list of specs, 
each of which is a list containing a character name and a function spec. The fol- 
lowing default asynchronous characters are defined for sirinteractive-stream: 

( :defaul t-init-pl ist 

: asynchronous-characters 

' ( (#\c-abort tv : kbd-asynchronous-i ntercept-character) 
(#\c-m-abort tv : kbd-asynchronous-i ntercept-character) 
(#\c-suspend tv : kbd-asynchronous-i ntercept-character) 
(#\c-m-suspend tv : kbd-asynchronous-i ntercept-character) ) ) 

Thus, tvrkbd-asynchronous-intercept-character is the standard handler for all of 
the system's asynchronous characters. The rhandle-asynchronous-character 
method for sirinteractive-stream calls this function with two arguments, the char- 
acter and the stream. 



tvrautoexposing-more-mixin Flavor 

If you mix in this flavor, when a rmore-exception happens, the window will be ex- 
posed (a rexpose message will be sent to it). This is intended to be used in con- 
junction with having a deexposed typeout action of rpermit, so that a process can 
type out on a deexposed window and then have the window expose itself when a 
xxMORExx break happens. 



tvrback-convert-constraints constraints Function 

Converts a list used as the rconstraints init option for tvrbasic-constraint-frame 
to a list suitable for the rconfigurations option. 
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The function returns two values: a list suitable for use as the argument to the 
rconfigurations option, and a list of symbols naming the panes encountered in the 
list. 

Example: 

(tv : back-convert-constrai nts 

' ((f i rst-conf ig . ((top-strip main-pane) 

((top-strip :horizontal (.3) 

(huey dewey louie) 
((huey :even) 
(dewey :even) 
(louie :even)))) 
((main-pane :even)))) 
(second-conf ig . ((main-pane bottom-strip) 

((bottom-strip :horizontal (.2) 

(random-pane menu) 
((menu :ask : pane-size)) 
((random-pane :even)))) 
((main-pane :even)))))) 

=> ((fi rst-conf ig (:layout 

(fi rst-conf ig :column top-strip main-pane) 
(top-strip : row huey dewey louie)) 
( :sizes 
(top-strip (huey :even) (dewey :even) (louie :even)) 
(fi rst-conf ig (top-strip 0.3) 

:then (main-pane :even)))) 
(second-conf ig (: layout 

(second-conf ig :column main-pane bottom-strip) 
(bottom-strip : row random-pane menu)) 
( :sizes 
(bottom-strip (menu :ask :pane-size) 

:then (random-pane :even)) 
(second-conf ig (bottom-strip 0.2) 

:then (main-pane :even))))) 

(random-pane menu main-pane louie dewey huey) 



(flavorrmethod :backspace-not-overprinting-flag tvrsheet) x Init Option 

If x is 0, typing #\back-space will move the cursor position backward; if it is 1, 
typing #\back-space will display "overstrike" in a lozenge (that is, #\back-space 
will be just like other special characters). It defaults to 0. 



si:backtranslate-font font Function 
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Returns the character style object corresponding to a specified screen font. Also re- 
turned are the character set, charset-offset, and device type. (The default device 
type for this function is si:*b&w-screen*.) 

Example: 

(si :backtranslate-font fonts :eurex24i) ==> 

#<CHARACTER-STYLE EUREX. ITALIC . HUGE 260273114> 

#<STANDARD-CHARACTER-SET 260000540> 



#<B&W-SCREEN-DI SPLAY-DEVICE 260272253> 



(flavorrmethod rbaseline tvrsheet) Method 

Returns the baseline of the current font. The bases of all output characters are so 
aligned as to be this many pixels below the top of the line on which the characters 
are printed. 

The baseline is affected by the value of the :bind-line-height option to character 
style macros. 

See the section "Table of Program Output Facilities". 



tvrbasic-choose-variable-values Flavor 

The basic flavor which makes a window implement the choose-variable-values fa- 
cility. It is built out of tvrtext-scroll-window. There are two ways to use this. In 
the first way, the programmer creates a window giving all of the parameters in 
the init-plist. In the second way one can create a window without specifying the 
parameters, then send the rsetup message to start the display. 



tv:basic-frame Flavor 

Provides methods that allow the frame to serve as the representative window of its 
activity. Usually a frame cannot become the selected window, but this flavor pro- 
vides methods that handle messages about selection, typically by operating on the 
selected-pane instead of the frame. The rselect, rdeselect, and : select-relative 
methods just pass these messages on to the selected-pane when one exists; other- 
wise they return nil. 

This flavor provides a handler for the :select-pane message that decides which 
pane should be selected when the activity is selected. The rinferior-select method 
saves the argument as the selected-pane and sends the message on to the frame's 
superior with the frame as argument. The :name-for-selection method returns the 
name-for-selection of the selected-pane if a selected-pane exists and has a name- 
for-selection; otherwise, the method returns the name of the frame. 



tv:basic-menu Flavor 
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All the other menus in the standard menu facility are built on this flavor. The ba- 
sic menu handles an item list, it remembers the last item selected, and it knows 
about its geometry. See the section "The Geometry of a Menu". 



tv:basic-momentary-menu Flavor 

When this flavor is mixed with a window, it creates a kind of menu that is only 
momentarily on the screen. A rchoose operation on a deexposed menu of this fla- 
vor causes it to position itself where the mouse is and expose itself. When the 
user selects an item in the menu, or alternatively moves the mouse far away from 
the menu, the menu disappears and deactivates. 



tv:basic-mouse-sensitive-items Flavor 

Mixing this flavor into a window provides for areas of the screen that are sensitive 
to the mouse. Moving the mouse into such an area highlights the area by drawing 
a box around it. At this point clicking the mouse performs a user-defined opera- 
tion. This flavor is called basic because it usurps the handling of the mouse by the 
window; do not mix it with another flavor that also expects to use the mouse. 
However it is less basic than many basic flavors in that it does not do anything 
special with the displayed image of the window. 



tvrbasic-multiple-choice Flavor 

The basic flavor that makes a window implement the multiple-choice facility. Like 
other basic flavors, it is not instantiable on its own but it does commit any window 
that incorporates it to being a multiple-choice window, tvrbasic-multiple-choice is 
built out of tvrtext-scroll-window. 



tv:basic-scroll-bar Flavor 

Provides basic scroll-bar scrolling. 



(flavorrmethod rbitblt tvrsheet) alu void hei from-raster from-x from-y to-x to-y 

Method 

Copy a rectangle of bits from from-raster onto the window. The rectangle has di- 
mensions width by height, and its upper left corner has coordinates (from-x, 
from-y). It is transferred onto the window so that its upper left corner will have 
coordinates (to-x, to-y). The bits of the transferred rectangle are combined with the 
bits on the display according to the Boolean function specified by alu. As in the 
bitblt function, if from-raster is too small it is automatically replicated. 

For complete details: See the function bitblt. Note that to-raster is constrained as 
described in the the description of the bitblt function. Use :draw-l-bit-raster 
rather than rbitblt in programs that run without modification on color screens. See 
the function tv:make-sheet-bit-array. 
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(flavorrmethod :bitblt-from-sheet tvrsheet) alu wid hei from-x frora-y to-raster to-x 
to-y Method 

Copy a rectangle of bits from the window to to-raster. All the other arguments 
have the same significance as in the rbitblt method of tvrsheet. Note that to-raster 
is constrained as described in the the description of the bitblt function. See the 
function tv:make-sheet-bit-array. 



(flavorrmethod rbitblt-within-sheet tvrsheet) alu wid hei from-x frora-y to-x to-y 

Method 

Copies a rectangle of bits from the window to some other place in the window. All 
the other arguments have the same significance as in the rbitblt method of 
tvrsheet. 



(flavorrmethod rblinker-p tvrsheet) t-or-nil Init Option 

Boolean option specifying whether to provide a blinking cursor when the window is 
exposed; the default is t. For more information on blinkers, see the section "Blink- 
ers". 



rblip-handler function Option 

Specifies a function to handle blips received while inside the input editor, function 
must be a function of two arguments. The first argument is the blip; the second 
argument is the stream that received the blip. The handler is invoked when the 
input editor receives a blip. If the handler returns non-nil, no further action is 
taken. If it returns nil and a rpreemptable option is in effect, the actions specified 
by that option are taken. Otherwise, the default blip handler is invoked. 

In the following example, the user is prompted for a line of text. While entering 
this text, the user may also click the left or middle mouse buttons. If the left 
mouse button is clicked, the coordinates of the mouse with respect to the window 
are inserted into the input buffer. If the middle button is clicked, the name of the 
window is inserted. 

(defun example-blip-handler (blip ignore) 

(destructuring-bind (type click window x y) blip 
(and (eq type : mouse-button) 
(selectq click 
(#\mouse-l-1 
(si : ie-insert-string (format nil " ~D ~D" x y)) 
t) 

(#\mouse-m-1 
(si : ie-insert-string (format nil " ~A" window)) 
t))))) 

(with-input-edi ting-options (( :bl ip-handler 'example-bl ip-handler)) 
(prompt-and-read :string "Blip handler test: ")) 
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si:ie-insert-string is an internal function for inserting a string into the input buf- 
fer. Since the language for writing input editor commands has not been formal- 
ized, this example might not work in a later release. 



(flavorrmethod :border-margin-width tv:borders-mixin) n-pixels Init Option 

Set the width of the white space in the margins between the borders and the in- 
side of the window. The default is 1. If some edge does not have any border (the 
specification for that border was nil), that border won't have any border margin 
either, regardless of the value of this option; that is the difference between border 
specifications of and nil. 



(flavorrmethod rborder-margin-width tvrborders-mixin) Method 

Returns the value of the border margin width. 

tvrbordered-constraint-frame Flavor 

Just tvrconstraint-frame with tvrborders-mixin mixed in at the right place. It will 
have a border around the edge. By default (using the rdefault-init-plist option of 
the flavor system), the rborder-margin-width is zero, so the panes at the edges of 
the frame are right next to the border itself. 

tvrbordered-constraint-frame-with-shared-io-buffer Flavor 

Like tvrconstraint-frame-with-shared-io-buffer except that it has tvrborders- 
mixin mixed into it at the right place, so that the frame has a border around it. 

(flavorrmethod rborders tvrborders-mixin) argument Init Option 

Initializes the parameters of the borders, argument may have any of the following 
values: 

nil There are no borders at all. 

a symbol or a number 

A specification which applies to each of the four borders. 

a list (left top right bottom) 

Specifications for each of the four borders of the window. 

a list (keywordl sped keyword2 spec2...) 

Specifications for the borders at the edges selected by the keywords, which 
may be among rleft, rtop, rright, rbottom. 

Each specification for a particular border may be one of the following. It specifies 
how thick the border is and the function to draw it. 

nil This edge should not have any border. 
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t The border at this edge should be drawn by the default function with the 

default thickness. 

a number 

The border at this edge should be drawn by the default function with the 
specified thickness. 

a symbol 

The border at this edge should be drawn by the specified function with the 
default thickness for that function. 

a cons (function . thickness) 

The border at this edge should be drawn by the specified function with the 
specified thickness. 

The default (and currently only) border function is tvrdraw-rectangular-border. 
Its default width is 1. 

To define your own border function, you should create a Lisp function that takes 
six arguments: the window on which to draw the label, the "alu function" with 
which to draw it, and the left, top, right, and bottom edges of the area that the 
border should occupy. The returned value is ignored. The function runs inside a 
tv:sheet-force-access. You should place a tv:default-border-size property on the 
name of the function, whose value is the default thickness of the border; it will be 
used when a specification is a non-nil symbol. 

Note that setting border specifications to ask for a border width of zero is not the 
same thing as giving nil as the argument to this option, because in the former 
case the space for the border margin width is allocated, whereas in the latter case 
it is not. 



(flavorrmethod rborders tvrmenu) argument Init Option 

Initializes the parameters of the borders. The argument can be nil, which specifies 
no borders, t, which specifies default borders, or it can be a specification of a bor- 
der. The specification indicates which function is used to draw the border and how 
thick the border is, in pixels. 

If the specification is a number, the border is drawn by the default function at the 
specified thickness. The default function is tvrdraw-rectangular-border. 

If the specification is a symbol, the border is drawn by the specified function at a 
default thickness. For more details on creating a function: See the section "Using 
the Window System". 

If the specification is a cons in the form (function . thickness), the borders are 
drawn by the specified function at a specified thickness. 

The specification can also be a list of locations on the screen: (left top right bot- 
tom). 



tvrborders-mixin Flavor 
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Creates the borders around windows that you often see when using Genera. You 
can control the thickness of each of the four borders separately, or of all of them 
together. You can also specify your own function to draw the borders, if you want 
something more elaborate than simple lines. 

The borders also include some white space left between the borders and the inside 
of the window. The thickness of this white space is called the border margin 
width. The space is there so that characters and graphics that are up against the 
edge of the inside of the window, or the next-innermost margin item, do not 
"merge" with the border. 



(flavorrmethod rbottom tvrmenu) bottom-edge Init Option 

Specified in pixels and is relative to the outside of the superior window. 

(flavorrmethod rbottom tvrsheet) bottom-edge Init Option 

Specifies the y-coordinate of the bottom edge of the window. 

(flavorrmethod rbottom-margin-size tvrsheet) Method 

Returns the bottom margin size of the window in pixels. 

tvrbox-blinker Flavor 

Like tvrhollow-rectangular-blinker, except that it draws a box two pixels thick, 
whereas the tvrhollow-rectangular-blinker draws a box one pixel thick. This fla- 
vor includes tvrrectangular-blinker, so all of tvrrectangular-blinker's init options 
and messages work on this too. 

dwrbox-bottom box Function 

Returns the location of the bottom of box. 



dwrbox-contained-in-region-p box other-left other-top other-right other-bottom 

Function 

Returns t if box is contained in the region defined by other-left, other-top, other- 
right, and other-bottom; otherwise, returns nil. Any of the other coordinates can be 
nil, meaning positive or negative infinity in the appropriate direction. 



dwrbox-edges box Function 

Returns four values in the following order: the location of the left-hand edge of 
box, of the top, of the right-hand edge, and of the bottom. 
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dw:box-left box 

Returns the location of the left-hand side of box. 



Function 



dw:box-right box 

Returns the location of the right-hand side of box. 



Function 



dw:box-top box 

Returns the location of the top of box. 



Function 



dw:boxes-overlap-p box-1 box-2 

Returns t if box-1 and box-2 overlap; otherwise, nil. 



Function 



cprbuild-command command-name &rest command-arguments Function 

Constructs the internal representation of a Command Processor command. 

command-name 

Symbol or string naming the command to invoke; if a string, it 
must be in the command table to which cp:*command-table* is 
currently bound. 

command-arguments 

Positional and keyword arguments to the named command, either 
strings or appropriate objects (or single objects when a sequence is 
required. 

Examples: 

(cp: build-command "show file" "test-data. text") => 
(SI :C0M-SH0W-FILE (#P"V :>elm>test-data. text . newest") ) 

(cp: build-command 'si :com-load-system "doc" 

condition :always : redef initions-ok t) => 
(SI:COM-LOAD-SYSTEM #<SCT : SYSTEM DOC 274003470> 

CONDITION :ALWAYS : REDEFINITIONS-OK T) 

Note how, in the first example, cprbuild-command "knows" the fact that com-show- 
file requires a sequence as its argument. It also parses strings into objects. It 
does all this by running the command parser in a mode that takes its input from 
the command arguments instead of from the keyboard. This is what makes 
cprbuild-command useful. Suppose, for example, you want to output a command as 
a presentation: 
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(present (cp: build-command 'si :com-show-f ile #p"Y:>elm>foo.bar") 

'cp: command) => 
Show File (file) Y:>elm>foo.bar 
#<DW: :DISPLAYED-PRESENTATION (SI : COM-SHOW. . . CP:COMMAND 447504140> 

You should not use cprbuild-command within a define-presentation-to-command- 
translator macro. It is too slow and you can encounter context problems in this 
use if the command is a program command whose parsing depends on the pro- 
gram's dynamic state. Instead of: 

(def i ne-presentati on-to-command-transl ator com-add-comment 
(node 

: gesture nil) 
(node) 
(cp: build-command 'com-add-comment node)) 

Do this instead: 

(def i ne-presentati on-to-command-transl ator com-add-comment 
(node 

: gesture nil) 
(node) 
1 (com-add-comment , node)) 



dw:call-presentation-menu menu-type &key .-presentation .-original-presentation .-win- 
dow .-label :x :y &allow-other-keys Function 

Used within a define-presentation-action that uses the :define-menu option, calls 
up the specified presentation menu. For example, the following form is used to set 
up the marking and yanking menu in the Lisp Listener: 

(define-presentation-action marking-and-yanking-menu 
(raw-text si : input-editor 

documentation "Marking and yanking menu" 
: gesture : marki ng-and-yanki ng-menu 
:menu (t :style (nil :italic nil)) 
:def ines-menu : marki ng-and-yanki ng) 
(ignore &key presentation 

(original-presentation presentation) window x y) 
(let ((use-presentation 

(or original-presentation presentation))) 
(return- from marking-and-yanking-menu 

(cal 1 -presentation-menu : marki ng-and-yanki ng 

: label 
(when 

(eq use-presentation 

xnul 1 -presentation*) 
"Marking and yanking operations") 
presentation use-presentation 
:window window :x x :y y)))) 
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Note that the menu-type argument to dw:call-presentation-menu is the one speci- 
fied by :defines-menu. The rlabel keyword argument is used to specify the result- 
ing menu's label. The values of the other keyword arguments are obtained from 
values available within the define-presentation-action form. Also note the use of 
return-from to cause the presentation action to return whatever values the han- 
dler invoked from the menu returns. This goes outside the scope of the nil from 
the expansion of define-presentation-action, since actions normally only have side 
effects. 



dwrcall-presentation-mouse-handler presentation &rest arguments &key :mouse- 
char .-window &allow-other-keys Function 

Invokes the translator for the mouse-click handler of presentation. This is for use 
within an input-blip handler. For example: 

(defun dynamic-window-presentation-input-bl ip-handler (blip) 
(destructuring-bind (nil mouse-char window x y) blip 
(cal 1 -presentation-mouse-handler 

(send window :displayed-presentation-at-position x y t) 
:mouse-char mouse-char 
:x x 

:y y 

:window window))) 
The arguments are the values of the blip. See the section "Mouse Blips". 

(flavorrmethod rcenter-around tv:essential-set-edges) x y Method 

Without changing the size of the window, positions the window so that its center 
is as close to the point (x,y), in pixels, relative to the superior window, as is possi- 
ble without hanging off an edge. 

(flavorrmethod :change-of-size-or-margins tvrsheet) &rest options Method 

Changes window size or margins, processing options. This message is sent by the 
system; you might need to provide an rafter daemon for it. 

tvrchangeable-name-mixin Flavor 

Mixing in this flavor defines a :set-name method, so that you can change the 
name of the window, redrawing the label if appropriate. This flavor includes 
tvrlabel-mixin, so one of the above kinds of label must be in the margins of the 
window. 

(flavorrmethod rchar tvrcharacter-blinker) char Init Option 

Sets the character to display. You must provide this. 
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char-mouse-bits char Function 

Returns the value of the bits field of a mouse character. The bits field encodes the 
shift keys, if any, qualifying the root mouse character: 

Bits Shift Key 

None 

1 CONTROL 

2 METR 
4 SUPER 
8 HYPER 
16 SHIFT 

Every combination of shift keys corresponds to a unique bits value, for example: 

(char-mouse-bits #\c-s-sh-Mouse-L) ==> 
21 



char-mouse-button char Function 

Returns the number corresponding to the mouse button that would have to be 
pushed to generate char. 0, 1, and 2 correspond to the Left, Middle, and Right 
mouse buttons, respectively. 

Example: 

(char-mouse-button #\m-mouse-m) ==> 
1 

The complementary function is make-mouse-char. 



char-mouse-equal charl char2 Function 

Returns t if the mouse characters charl and char2 are equal, nil otherwise, char- 
mouse-equal checks that its arguments are really mouse characters and signals an 
error otherwise. You can also use eql, which is slightly faster, to compare mouse 
characters, when you do not require the argument checking. 



tvrcharacter-blinker Flavor 

Draws itself as a character from a font. You can control which font and which 
character within the font it uses. 



(flavorrmethod rcharacter-height tvrmenu) spec Init Option 

Specifies the height of the window. The inside height of the window is made large 
enough to display spec number of lines in the default character style. If the spec is 
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a string containing carriage returns, then it is made tall enough to accommodate 
the string. 



(flavorrmethod rcharacter-height tvrsheet) spec Init Option 

Specifies the height, spec is either a number of lines or a character string contain- 
ing a certain number of lines separated by carriage returns. The inside height of 
the window is made to be that many lines. 



(flavorrmethod rcharacter-width tvrmenu) spec Init Option 

Specifies the width of the window. The inside width of the window is made large 
enough to display spec number of characters in the default character style. If the 
spec is a string, then it is made wide enough to display the string. 



(flavorrmethod rcharacter-width tvrsheet) spec Init Option 

Another way of specifying the width, spec is either a number of characters or a 
character string. The inside width of the window is made to be wide enough to 
display those characters, or that many characters, in the default character style. 



(flavorrmethod rcharacter-width tvrsheet) ch &optional font (x tvrcursor-x) char- 
acter-style Method 

Returns the width of the character ch, in pixels. The font used is font or the font 
resulting from merging character-style with the current character style. See the 
section "Merging Character Styles". If ch is a Backspace, rcharacter-width can re- 
turn a negative number. For Tab, the number returned depends on the current 
cursor position. If ch is Return, the result is defined to be zero. 



dwrcheck-presentation-type-argument type-arg &key (evaluated t) (function 
compilerrdefault-warning-function) (definition-type compilerrdefault-warning- 
definition-type) Function 

Checks an argument that is expected to be a presentation type for validity. 
type-arg A form evaluating to a presentation type. 

revaluated 

Boolean option specifying whether type-arg is expected to be quoted; 
the default is t. 

rfunction Specifies a symbol naming the function for which the compiler 
warning is issued. This name is displayed in the warning instead of 
the name of the function in which the error occurred; the latter be- 
havior is the default. 
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: definition- type 

Specifies the definition type ('defun, 'defvar, etc.) of the Lisp object 
that caused the compiler warning. The name for objects of this type 
("Function", "Variable", etc.) is displayed in the warning instead of 
the name for the type of object in which the error occurred; the lat- 
ter behavior is the default. 

This function should be used in macros that take presentation types as arguments 
and in style-checkers for functions that take presentation types. 

Here is an example of the use of dw:check-presentation-type-argument in a 
macro: 

(def macro with-value ((variable-name presentation-type) &body body) 
(dw: check-presentation-type-argument presentation-type : evaluated nil) 
'(let ((, variable-name (accept ', presentation-type))) 
,@body)) 

If you try to compile the following function, which contains an invalid specification 
of the integer presentation type inside an invocation of with-value, you get a com- 
piler error diagnosing the problem: 

(defun check-type-test () 

(with-value (x ((integer 3 5 extra-argument))) 
(format t "~&\/alue is ~S" x))) 

The revaluated keyword is used to control whether dw:check-presentation-type- 
argument expects the presentation type to be quoted or not. In the macro example 
above, the presentation type is inserted unquoted into the invocation of the with- 
value macro. If you wanted with-value to evaluate its presentation-type argument 
(for instance, so that a variable that was bound to a presentation type could be 
used), then you would supply : eval uated t (the default). The rewritten example 
follows: 

(def macro with-value ((variable-name presentation-type) &body body) 
(dw: check-presentation-type-argument presentation-type evaluated t) 
'(let ((, variable-name (accept , presentation-type))) 
,@body)) 

(defun check-type-test () 

(with-value (x '((integer 3 5 extra-argument))) 
(format t "~&\/alue is ~S" x))) 

See the section "Defining Your Own Presentation Types". 

(In both of the above examples, multiple error messages result because accept it- 
self uses dw:check-presentation-type-argument to validate its arguments.) 

For an overview of dw:check-presentation-type-argument and related facilities: 
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(flavorrmethod rchoose tvrmenu) Method 

Exposes the window and allows the user to make a choice with the mouse. It sends 
rexecute to the window and performs the action specified by the item's type. 



(flavorrmethod rchoose tvrmultiple-choice) &optional near-mode Method 

Allows menu selection by the mouse. It first moves the window to the place speci- 
fied by near-mode, which defaults to the list (rmouse), (that is, over the current 
mouse position) and exposes it. Then it waits for the user to make a finishing 
choice and returns the window to its original activate/expose status before the 
rchoose operation. When it is sent to a multiple-choice menu, this message returns 
the same value as the function tvrmultiple-choose. See the section "The Standard 
Multiple Choice Function". 



cprchoose-command-arguments command-name &rest args &key (initial-arguments 
nil) (start (length cprrinitial-arguments)) (end nil) (command-table cpr*command- 
table*) (stream *standard-input*) (typeout-stream nil) (help-stream cprrtypeout- 
stream) (prompt-mode mormal) (near-mode '(rmouse),) (mode r accept- values) (type- 
out-stream nil) (help-stream cprrtypeout-stream) (prompt nil) (own-window nil) (full- 
rubout nil) (erase-input-editor nil) (initially-select-query-identifier nil) Function 

Returns arguments for the command command-name in one of three possible 
modes: raccept-values, the default, displays an accept-values-type of menu with 
which the user selects arguments; rkeyboard allows the user to edit the command 
arguments from the keyboard; and mone returns default values for the positional 
arguments. 

rinitial-arguments 

The arguments initially supplied. These are used as defaults or ini- 
tial values in non raccept-values mode. 

rstart The number of arguments initially supplied that should be retained 
unmodified. This option is only used when the rmode is rkeyboard. 

rend The number of arguments initially supplied that should be retained 

unmodified. This option is only used when the rmode is raccept- 
values. 

rcommand-table 

Specifies the command table containing the command; the default is 
the current command table (bound to cpr*command-table*). 

rstream Specifies the input stream; the default is *standard-input*. 

rtypeout-stream 

The typeout window to use in raccept-values mode. 

rhelp-stream 
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The stream to which responses to requests for help should be di- 
rected. The default is the value specified for rtypeout-stream. 

rprompt Specifies a string, or a function returning a string, serving as the 
prompt or as the window label if :own-window is true. 

:prompt-mode 

Specifies how the prompt is to be displayed. The default is rnormal, 
which means display the prompt even if the accept-values display is 
not in ": own-window." The value :own- window means only show the 
prompt as a label. 

:own-window 

A Boolean option specifying when t that the accept-values-like menu 
be displayed in its own window. The default is nil. 

:full-rubout 

Specifies when non-nil that if the user rubs out all the characters 
that were typed, control is returned immediately. Two values are 
returned: nil and the value specified for :full-rubout. If this option 
is nil, the input editor waits for more characters to be typed. This 
option applies only when the :mode is rkeyboard. 

:erase-input-editor 

A Boolean specifying when t that the menu used should be erased 
when done if called from inside the input editor. This is useful if 
you are going to :replace-input the command line next anyway. The 
default is nil. 

:near-mode 

Specifies where the menu appears. The default makes it appear 
near the position of the mouse cursor at the time the function is 
called. See the method (flavorrmethod :expose-near tvressential- 
set-edges).This option is applicable only when the value of the 
:own-window option is t. 

:mode Specifies mode for choosing. One of 

: accept-values The default. Provides a menu-like facility for 

setting the values of the command arguments to 
values supplied by the user. 

menu The same as raccept-values. 

rkeyboard Applies cprread-command-arguments for the 

specified command and returns them. 

rnone Defaults the positional arguments of the speci- 

fied command. 

rinitially-select-query-identifier 
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Specifies a field to be pre-selected when the user interaction begins. 
This is the same as the dw: accept- values rinitially-select-query- 
identifier option, see the function dwraccept-values. 



choose-user-options alist &rest options Function 

Displays the values of the option variables in alist to the user and allows them to 
be altered. The options are passed along to tvrchoose-variable-values. 



tvrchoose-variable-values variables &rest options Function 

Exposes a window and displays the values of the specified variables, permitting the 
user to alter them. One or more choice boxes (as in the multiple-choice facility) 
appear in the bottom margin of the window. When the user clicks on the [Exit] 
choice box the window disappears and this function returns. The value returned is 
not meaningful; the result is expressed in the values of the variables. 

variables is a list whose elements can be special variables or the more general 
items described above. 

options is a list of alternating init-plist option keywords and values: 

The following option keywords can be specified. 

(flavorrmethod rlabel tvrchoose-variable-values) 
(flavorrmethod rfunction tvrchoose-variable-values) 
(flavorrmethod rnear-mode tvrchoose-variable-values) 
(flavorrmethod rwidth tvrchoose-variable-values) 
(flavorrmethod rextra-width tvrchoose-variable-values) 
(flavorrmethod rmargin-choices tvrchoose-variable-values) 
(flavorrmethod rsuperior tvrchoose-variable-values) 



See the section "tvrchoose-variable-values Examples". 



tvrchoose-variable-values-pane Flavor 

A tvrchoose-variable-values-window that can be a pane of a constraint-frame. For 
more on constraint frames, see the section "Specifying Panes and Constraints". It 
does not change its size automatically; the size is assumed to be controlled by the 
superior. 



tvrchoose-variable-values-process-message window command Function 

Implements the proper response. It should be called in the process and stack-group 
in which the variables being chosen are bound. The function returns t if the com- 
mand indicates that the choice operation is "done", otherwise it performs the ap- 
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propriate special action and returns nil. If command is a character, it is ignored 
unless it is the #/si:refresh key, in which case the choose-variable-values window is 
refreshed. 



tvrchoose-variable-values-window Flavor 

A choose-variable-values window with a reasonable set of features, including bor- 
ders, a label at the top, stream input/output, the ability to be scrolled if there are 
too many variables to fit in the window, and the ability to have choice boxes in the 
bottom margin. 



(flavorrmethod :clear-char tvrsheet) &optional char Method 

Erases the character at the current cursor position. When using character styles 
mapping to variable-width fonts, you tell it the character you are erasing, so that 
it will know how wide the character is. If you don't pass the char argument, it 
simply erases a character-width, which is fine for fixed-width fonts. 



(flavorrmethod rclear-history dw: dynamic- window) Method 

Eliminates all items in the output history of the window, and resets the viewport 
to the top of the history. 

For an overview of (flavorrmethod rclear-history dwr dynamic- window) and relat- 
ed facilities, see the section "Presenting Formatted Output". 



(flavorrmethod rclear-input sirinteractive-stream) Method 

Clears the input buffer and any input buffered by the stream. This flushes all the 
characters that have been typed at this stream, but have not yet been read. 



(flavorrmethod rclear-input tvrstream-mixin) Method 

Clears this window's input and I/O buffers. It flushes all the characters that have 
been typed at this window but have not yet been read. 



dwrclear-presentation-input-context Function 

Clears the current input context. This is useful for eliminating the input context 
established by a function's callers in order to establish a new input context that 
doesn't inherit from the callers. 

For an overview of dwrclear-presentation-input-context and related facilities: See 
the section "Presentation Input Context Facilities". 



(flavorrmethod rclear-region dwr dynamic- window) left top right bottom Method 
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Clears the output display in a rectangular area of the window. Specify the region 
in terms of absolute window coordinates. Any coordinate can be given a value of 
nil to indicate infinite extent in that direction. 

left The x-coordinate for the left edge of the cleared area. 

top The y-coordinate for the top edge of the cleared area. 

right The x-coordinate for the right edge of the cleared area. 

bottom The y-coordinate for the bottom edge of the cleared area. 

For an overview of (flavorrmethod rclear-region dw: dynamic- window) and related 
facilities, see the section "Presenting Formatted Output". 

(flavorrmethod :clear-rest-of-line tvrsheet) Method 

Erases from the current cursor position to the end of the current line; that is, 
erases a rectangle horizontally from the cursor position to the inside right edge of 
the window, and vertically from the cursor position to one line-height below the 
cursor position. 

(flavorrmethod :clear-rest-of-window tvrsheet) Method 

Erases from the current cursor position to the bottom of the window. In more de- 
tail, first does a rclear-rest-of-line, and then clears all of the window past the cur- 
rent line. 

(flavorrmethod rclear-window dwr dynamic- window) Method 

Scrolls the window forward in the vertical dimension far enough to eliminate pre- 
vious output from the current display. Note that only the display is affected, not 
the window's output history. 

For an overview of (flavorrmethod rclear-window dwr dynamic- window) and relat- 
ed facilities, see the section "Presenting Formatted Output". 

(flavorrmethod rclear-window tvrsheet) Method 

Erases the whole window and move the cursor position to the upper left corner of 
the window. 

tvrcold-load-stream-old-selected-window Variable 

At a cold-load-stream break, the value is the value of tvr selected- window at the 
time you entered the cold-load stream. 
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(flavorrmethod :column-spec-list tv:dynamic-multicolumn-mixin) form 

Init Option 

Specified as a list of columns in the form: 

(heading item-list-form . options) 

Heading is a string to go at the top of the column, and options are menu item op- 
tions for it (typically a character style specification), item-list-form is a form to be 
evaluated (without side-effects) to get the item list for that column. 

(flavorrmethod rcolumns tvrmenu) n-columns Init Option 

Sets the number of columns in a menu. 

rcommand function &rest arguments Option 

This option is used to implement nonediting single-keystroke commands. For each 
character typed, the input editor invokes function with the character as the first 
argument and arguments as the remaining arguments. If the function returns nil, 
the input editor processes the character as it normally would. Otherwise, control is 
returned from the input editor immediately. Two values are returned: a blip of the 
form (rcommand character numeric-arg) and the keyword rcommand. Any un- 
scanned input typed before the command character remains in the input buffer, 
available to the next read operation from the stream. 



cprcommand-in-command-table-p command-symbol command-table &optional (need- 
name t) Function 

Determines the presence of a command in a Command Processor command table. 
The function returns three values: t if the command is either in the specified com- 
mand table or in a table from which the specified table inherits; the command's 
name (a string) or, if need-name is nil, nil; and the command table in which the 
command was found. 

command-symbol 

The command symbol. 

command-table 

The command table. 

need-name 

A Boolean specifying whether the name (a string) of the command 
should be returned. By default, it is. The function runs faster when 
this is nil. 

For an overview of cprcommand-in-command-table-p and related facilities: See 
the section "Managing Your Program Frame". 
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tv:command-menu Flavor 

This is tv:command-menu-mixin mixed with tvrmenu to make it instantiable. 

tv:command-menu-abort-on-deexpose-mixin Flavor 

When a command menu built on this flavor receives the rdeexpose message, it 
searches its item list for an item whose displayed representation is [Abort]. If such 
an item is found, a mouse blip is sent to the I/O buffer indicating that the [Abort] 
item was clicked on. See the flavor tv:dynamic-pop-up-abort-on-deexpose- 
command-menu. 



dw:command-menu-choose-arguments command-name &rest args &key .-initial- 
arguments (: command-table cp:*command-table*) (.-gesture rleftj -.mode -.own-window 
Ofull-rubout t) &allow-other-keys Function 

Performs the normal actions taken by command menus. You can call this in addi- 
tion to special actions of your own for a command menu. 

command-name 

A string, which identifies the command-menu item. 

args The command arguments. 

rinitial-arguments 

Arguments already specified to the command (that do not need to 
be chosen). 

:command-table 

The command table that contains the command command-name. 

rgesture A single keyword, or list of keywords, identifying which gestures 
this handler applies to. A single handler can apply to more than one 
gesture, and multiple handlers can be defined on different gestures. 
The possible actions will then naturally be their union. 

:mode The mode in which to accept arguments. Possible values are 
rkeyboard, menu, and raccept-values. 

:own-window 

A Boolean option specifying when t that the accept-values-like menu 
be displayed in its own window. The default is nil. 

:full-rubout 

Specifies when non-nil that if the user rubs out all the characters 
that were typed, control is returned immediately. Two values are 
returned: nil and the value specified for :full-rubout. If this option 
is nil, the input editor waits for more characters to be typed. This 
option applies only when the :mode is rkeyboard. 

For an overview of related topics: See the section "How Command Menus Work". 
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tv:command-menu-mixin Flavor 

The basic mixin version of the command menu flavor. It is not instantiable on its 
own. 



tv:command-menu-pane Flavor 

This version of the command menu flavor is meant to be used within a window 
frame. See the section "Frames". 



dw: *command-menu- test-phase* Variable 

Bound to t during the rtester phase when a command form body is running, and 
to : documentation during the documentation phase. This for use within a 
dw:define-command-menu-handler form. The command body can throw to the tag 
dw:command-menu-test-phase with a command (list of command name and argu- 
ments) or with a string (in the documentation case). Note that if the command 
body pops up a menu or reads from the keyboard to get arguments, it must look at 
this flag to prevent doing so when except when the user really clicked. 

For an example of the use of the throw tag:See the section "How Command Menus 
Work". 



cp:*command-table* Variable 

Bound to the current command table, that is, the one used by the Command Pro- 
cessor when reading commands. 

For an overview of cp:*command-table* and related facilities: See the section 
"System Command Tables". 



dw:compare-char-for-accept char-from-accept comparandum Function 

Compares an input character with a specified character. Use this function instead 
of char-equal when manipulating characters read with dw:read-char-for-accept. 

char-from-accept 

The input character (returned by dw:read-char-for-accept). 

comparandum 

The comparison character. This may be any standard character. 

For an overview of dw:compare-char-for-accept and related facilities, see the sec- 
tion "Defining Your Own Presentation Types". 



dw:complete-from-sequence sequence stream &key type {name-key #'string) {value- 
key #'identity) {delimiters dw::*standard-completion-delimiters*) {allow-any-input 

nil) {enable-forced-return nil) {initially-display-possibilities nil) {partial-completers 
nil) {complete-activates nil) {compress-choices 20) {compression-delimiter ) Function 
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Provides input completion from a sequence of possible completions for input to 
accept. Returned values are the object associated with the completion string; t or 
nil depending on whether or not the completion was the only one possible; and the 
completion string. 



sequence The sequence of possible completions. 
stream The input stream. 



:type Specifies the presentation type to use when displaying help informa- 
tion for possible completions. This makes the displayed possibilities 
mouse-sensitive. 

If the completion utility is being called from the parser of a presen- 
tation type, that type should be supplied as the value of this option. 

:name-key 

Specifies the function called on each element in the sequence for 
extracting the completion string. The default function is string. An- 
other useful function is string-capitalize-words. 

rvalue-key 

Specifies the function called on each element in the sequence for 
extracting the value to be associated with the element's completion 
string. The default function is identity, which extracts the element 
itself. 

: delimiters 

Specifies a list of characters used by the standard completion mech- 
anism to tokenize completion strings. The default value is the bind- 
ing of dw::*standard-completion-delimiters*; this variable is preset 
to "- " (hyphen and space). 

:allow-any-input 

Boolean option specifying whether the completer accepts keyboard 
input from the user that does not match any of the possible comple- 
tion strings; the default is nil. 

Most parsers should specify :allow-any-input nil. In a call to 
accept for which you want to allow input that does not match any 
of the completions, use the type-or-string presentation type. 

Note that the completion facilities always signal the error 
dw:input-not-of-required-type when a user types RETURN at blank 
input. This is intended to allow accept to fill in the default in the 
blank case. It means, however, that a caller of a completion facility 
that passes :allow-any-input t must also condition-bind for 
dw:input-not-of-required-type, if you want a null line to be treated 
the same as any other input. 
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renable-forced-return 

Boolean option specifying whether the user can force a response 
that is not a member of the completion set; the default is nil. 

If this option is t, the user can terminate input with c-RETURN, 
causing the completion utility to return to the caller whatever input 
the user supplied. This is useful in situations where you expect the 
user to specify a member of a set of possibilities, but want to pro- 
vide a way for supplying a new name to be added to the set. (The 
Zmacs Select Buffer (c-K B) command uses this feature to allow the 
user to create new buffers.) 

rinitially-display-possibilities 

Boolean option specifying whether to display the entire set of com- 
pletion possibilities before prompting for input; the default is nil. If 
t, the behavior is as if the user typed Help before any other input. 

Most parsers should supply to this option the same value that was 
supplied to them by accept, accept, in turn, has an rinitially- 
display-possibilities option controlled by its caller. See the function 
accept. 

rpartial-completers 

Specifies a list of characters that trigger partial completion when 
entered by the user. 

Partial completion restricts completion to only one token of the 
completion set possibilities, even if enough characters have been 
supplied to uniquely identify one of the members of the completion 
set. For example, the Command Processor uses #\space as a partial 
completer. 

The syntax of a token is defined by the rdelimiters option. 

:complete-activates 

Boolean option specifying whether the COMPLETE key causes activa- 
tion, that is, whether the completion utility returns if a unique com- 
pletion was found. The default is nil. 

This option is used to control completion behavior in a multi-field 
input context, such as in the command processor. Normally, the END 
key performs completion and then returns if the resulting comple- 
tion is unique. 

:compress-choices 

Specifies whether to compress the display of completion possibilities 
that have a common left token as defined by the rcompression- 
delimiter option. Three values are possible: 

An integer 

When the possibilities exceed this number, the display is 
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compressed. The default value is 20. 

ralways Whenever more than one possibility exists, the display is 
compressed. 

rnever The display is never compressed, regardless of the number 
of possibilities. 

Compressed displays have the form "token ... in)", where token is the 
shared left token and n is the number of possible completions. 

To see an example of choice compression, press HELP to the com- 
mand processor prompt in a Dynamic Lisp Listener. You get the fol- 
lowing display (abbreviated for this example): 

You are being asked to enter a command or form. 
Use the Help : Format Detailed command to see a full 
list of command names. 

These are the possible command names: 
Add Paging File 
Append 
Clean File 
Clear ... (3) 
Close File 
Compare Directories 
Compile ... (2) 
Copy ... (5) 
Create ... (4) 
Debug Process 

"Add Paging File", "Append", and "Clean File" are full command 
names. "Clear" is a left token shared by three commands, Clear All 
Breakpoints, Clear Breakpoint, and Clear Output History. These 
three completion choices have been compressed to "Clear ... (3)". 
The user can expand this and other compressed choices by clicking 
on them with the mouse. 

rcompression-delimiter 

Specifies a character used for delimiting the shared left tokens in a 
display of completion possibilities. The default value is #\space. 

For an overview of dw:complete-from-sequence and related facilities, see the sec- 
tion "Introduction: More Presentation-Type Concepts". For a table of available 
functions relating to Presentation Types, see the section "Table of Facilities for 
Defining Presentation Types". 



:complete-help &rest help-option Option 
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When the user presses HELP, the input editor types out a message determined by 
help-option. None of the standard input editor help is displayed. If a :brief-help op- 
tion has been specified, it overrides :complete-help. :complete-help overrides 
:merged-help and :partial-help. 

help-option can have one element, which can be a string, a function, or a symbol; 
or it can have more than one element. For an explanation: See the section "Dis- 
playing Help Messages in the Input Editor". 

This option is intended for programs that supply their own input editor help mes- 
sages. 



dw:complete-input stream function &key (allow-any-input nil) enable-forced-return 
partial-completers (type nil) parser (compress-choices 20) (compression-delimiter ) 
(help-offers-possibilities t) (initially-display-possibilities nil) (complete-activates nil) 
(documenter nil) (document (not (null dw::documenter))) Function 

Provides input completion for input to accept. Returns three values: the object as- 
sociated with the completion string; t or nil depending on whether or not the com- 
pletion was the only one possible; and the completion string. dw:complete-input is 
a low level function that is called by dw:completing-from-suggestions. In most 
cases, the latter is easier to use and is recommended. Use dw:complete-input only 
when you require finer control over the completion operations than that allowed by 
dw:completing-from-suggestions. 

stream The input stream. 

function The completion function. The function receives two arguments, the 
input supplied by the user and a keyword specifying an operation. 

Operations are divided into two categories, completion operations 
and possibility operations. The former attempt to complete and re- 
turn the completion; the latter return either a list of possible com- 
pletions or the number of possible completions. Available keywords 
for each type are described below: 

Completion Operations 

rcompleteComplete and return as much as possible based on 
the input so far. 

rcomplete-limited 

Complete and return the current input "chunk" 
only, even if the input uniquely identifies a full 
completion possibility. The meaning of "chunk" de- 
pends on the type of input. For example, in the 
case of command processor commands, a chunk is 
a word in the command name. 

rcomplete-maximal 

Complete and return as much as possible based on 
the input so far, even if that means adding empty 
tokens between delimiters. 
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Regardless of the completion operation, the completion function 
must return the following five values: 

1. The string resulting from completing the input string. 

2. A boolean indicating that the completion is successful, 
that is, that the string given to the user-supplied function 
is itself a valid completion. 

3. The object associated with the completion if it is success- 
ful. (If the completion is not successful, the value of this 
is undefined, although it is often one of the objects in the 
ambiguous case where the completion is unsuccessful and 
the number of possibilities is greater than one.) 

4. The index in the completion string of the first point of 
ambiguity if the string is not unique, that is, the leftmost 
place in the string where a difference arises between two 
or more completion possibilities. The completer generally 
tries to position the input cursor at that point so that the 
user can resolve the ambiguity. 

5. The number of possible input completions; this may be 0. 
Possibility Operations 

rpossibilities 

Return a list of completion possibilities that begin 
with the input string. (This list is used, for example, 
when the user presses the HELP key.) 

: apropos-possibilities 

Return a list of the completion possibilities that con- 
tain the input string anywhere in the completion 
string. (This list is used, for example, when the user 
types CONTROL-/.) The function may split the input in- 
to tokens and search for possibilities that contain all 
the tokens somewhere in the completion string. In 
this case, it should return as a second value the list 
of tokens extracted from the original input string. 

: apropos-initial-possibilities 

Return a list of the completion possibilities that con- 
tain the input string in the completion string. 

:possibilities-quick-length 

Returns the number of completion possibilities that 
begin with the input string. 
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:apropos-possibilities-quick-length 

Return the number of completion possibilities that 
contain the input string anywhere in the completion 
string. 

If the possibility operation is rpossibilites or rapropos- 
possibilities, the function must return a list of three-element 
lists, each of which is (string object presentation-type). 

The completion function can return nil to indicate that it does 
not support the "quick-length" operations. In this case, the 
completer utility asks for a full rpossibilities or rapropos- 
possibilities list and counts the number of elements to return. 

:allow-any-input 

Boolean option specifying whether the completer accepts keyboard 
input from the user that does not match any of the possible comple- 
tion strings; the default is nil. 

Most parsers should specify :allow-any-input nil. In a call to 
accept for which you want to allow input that does not match any 
of the completions, use the type-or-string presentation type. 

Note that the completion facilities always signal the error 
dw:input-not-of-required-type when a user types RETURN at blank 
input. This is intended to allow accept to fill in the default in the 
blank case. It means, however, that a caller of a completion facility 
that passes :allow-any-input t must also condition-bind for 
dw:input-not-of-required-type, if you want a null line to be treated 
the same as any other input. 

renable-forced-return 

Boolean option specifying whether the user can force a response 
that is not a member of the completion set; the default is nil. 

If this option is t, the user can terminate input with c-RETURN, 
causing the completion utility to return to the caller whatever input 
the user supplied. This is useful in situations where you expect the 
user to specify a member of a set of possibilities, but want to pro- 
vide a way for supplying a new name to be added to the set. (The 
Zmacs Select Buffer (c-H B) command uses this feature to allow the 
user to create new buffers.) 

rpartial-completers 

Specifies a list of characters that trigger partial completion when 
entered by the user. 

Partial completion restricts completion to only one token of the 
completion set possibilities, even if enough characters have been 
supplied to uniquely identify one of the members of the completion 
set. For example, the Command Processor uses #\space as a partial 
completer. 
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The syntax of a token is defined by the rdelimiters option. 

:type Specifies the presentation type to use when displaying help informa- 
tion for possible completions. This makes the displayed possibilities 
mouse-sensitive. 

If the completion utility is being called from the parser of a presen- 
tation type, that type should be supplied as the value of this option. 

rparser Specifies the function called to translate input strings into objects 
of the desired type. The function is called with one argument, the 
string entered by the user. 

This option is typically used when the set of possible completions is 
not known in advance, and can therefore not be enumerated. If they 
can be enumerated, use dw:complete-from-sequence or 
dw:completing-from-suggestions instead. 

The parser function is called on each possible completion string 
when a list of possibilities is generated, and on the user-supplied in- 
put when the completion utility is about to return a value. 

rcompress-choices 

Specifies whether to compress the display of completion possibilities 
that have a common left token as defined by the rcompression- 
delimiter option. Three values are possible: 

An integer 

When the possibilities exceed this number, the display is 
compressed. The default value is 20. 

ralways Whenever more than one possibility exists, the display is 
compressed. 

rnever The display is never compressed, regardless of the number 
of possibilities. 

Compressed displays have the form "token ... (n)", where token is the 
shared left token and n is the number of possible completions. 

To see an example of choice compression, press HELP to the com- 
mand processor prompt in a Dynamic Lisp Listener. You get the fol- 
lowing display (abbreviated for this example): 

You are being asked to enter a command or form. 
Use the Help : Format Detailed command to see a full 
list of command names. 
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These are the possible command names: 
Add Paging File 
Append 
Clean File 
Clear ... (3) 
Close File 
Compare Directories 
Compile ... (2) 
Copy ... (5) 
Create ... (4) 
Debug Process 

"Add Paging File", "Append", and "Clean File" are full command 
names. "Clear" is a left token shared by three commands, Clear All 
Breakpoints, Clear Breakpoint, and Clear Output History. These 
three completion choices have been compressed to "Clear ... (3)". 
The user can expand this and other compressed choices by clicking 
on them with the mouse. 

rcompression-delimiter 

Specifies a character used for delimiting the shared left tokens in a 
display of completion possibilities. The default value is #\space. 

:help-offers-possibilities 

Boolean option specifying whether the full list of completion possi- 
bilities is displayed when the user presses the HELP key; the default 
is t. 

rinitially-display-possibilities 

Boolean option specifying whether to display the entire set of com- 
pletion possibilities before prompting for input; the default is nil. If 
t, the behavior is as if the user typed Help before any other input. 

Most parsers should supply to this option the same value that was 
supplied to them by accept, accept, in turn, has an rinitially- 
display-possibilities option controlled by its caller. See the function 
accept. 

rcomplete-activates 

Boolean option specifying whether the COMPLETE key causes activa- 
tion, that is, whether the completion utility returns if a unique com- 
pletion was found. The default is nil. 

This option is used to control completion behavior in a multi-field 
input context, such as in the command processor. Normally, the END 
key performs completion and then returns if the resulting comple- 
tion is unique. 
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rdocumenter 

Specifies a function called to generate documentation for the ele- 
ments of a possibilities display. The function receives two argu- 
ments, a completion possibility and the output stream for displaying 
the documentation. 

: document 

Specifies how each possibility displayed as a result of a HELP re- 
quest is documented. Three values are possible: 

t Display the documentation. If a documentation function 

is specified by the rdocumenter , option, it is called on 
each possibility; otherwise, the Common Lisp function 
documentation is called. 

nil Do not display any documentation. 

:if-uniqueDisplay documentation only if there is a unique comple- 
tion of the input supplied by the user. 

The default for this option is t if a rdocumenter function is sup- 
plied, nil otherwise. 

For an overview of dwrcomplete-input and related facilities, see the section 
"Defining Your Own Presentation Types". 



dw:completing-from-suggestions (stream &key (allow-any-input t) (delimiters 
dw::*standard-completion-delimiters*) (enable-forced-return nil) (partial-completers 

nil) (type nil) (parser nil) (complete-activates nil) (compress-choices 20) (compression- 
delimiter nil) (initially-display-possibilities nil)) &body body Function 

Binds local environment to build a completion table for input to accept. Three val- 
ues are returned: the object associated with the completion string; t or nil depend- 
ing on whether or not the completion was the only one possible; and the comple- 
tion string, that is, the fully completed string generated from what the user typed. 
Within this environment, you must use dwrsuggest within body to add each possi- 
ble choice to the completion table. 

stream The input stream. 

Here is an example, excerpted from a system definition: 



Page 1 185 



(def ine-presentati on-type keyword-argument ((&rest keywords)) 
: parser ((stream &key initial ly-display-possibil i ties type) 



(multiple-value-bind (word nil nil) 
(dw:completing-f rom-suggestions 
(stream : force-complete t 

: parti al -compl eters 

xkeyword-key-parti al -compl eters* 
: initial ly-display-possibil ities 

initial ly-display-possibil ities 
:type type 

:compress-choices :never) 
(loop for keyword-name being 

the array-elements of keyword-names 
for key being the array-elements of keys 

doing 
(dw: suggest keyword-name key))) 
word))))) 

:allow-any-input 

Boolean option specifying whether the completer accepts keyboard 
input from the user that does not match any of the possible comple- 
tion strings; the default is nil. 

Most parsers should specify :allow-any-input nil. In a call to 
accept for which you want to allow input that does not match any 
of the completions, use the type-or-string presentation type. 

Note that the completion facilities always signal the error 
dw:input-not-of-required-type when a user types RETURN at blank 
input. This is intended to allow accept to fill in the default in the 
blank case. It means, however, that a caller of a completion facility 
that passes :allow-any-input t must also condition-bind for 
dw:input-not-of-required-type, if you want a null line to be treated 
the same as any other input. 

: delimiters 

Specifies a list of characters used by the standard completion mech- 
anism to tokenize completion strings. The default value is the bind- 
ing of dw::*standard-completion-delimiters*; this variable is preset 
to "- " (hyphen and space). 

renable-forced-return 

Boolean option specifying whether the user can force a response 
that is not a member of the completion set; the default is nil. 

If this option is t, the user can terminate input with c-RETURN, 
causing the completion utility to return to the caller whatever input 
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the user supplied. This is useful in situations where you expect the 
user to specify a member of a set of possibilities, but want to pro- 
vide a way for supplying a new name to be added to the set. (The 
Zmacs Select Buffer (c-K B) command uses this feature to allow the 
user to create new buffers.) 

rpartial-completers 

Specifies a list of characters that trigger partial completion when 
entered by the user. 

Partial completion restricts completion to only one token of the 
completion set possibilities, even if enough characters have been 
supplied to uniquely identify one of the members of the completion 
set. For example, the Command Processor uses #\space as a partial 
completer. 

The syntax of a token is defined by the rdelimiters option. 

:type Specifies the presentation type to use when displaying help informa- 
tion for possible completions. This makes the displayed possibilities 
mouse-sensitive. 

If the completion utility is being called from the parser of a presen- 
tation type, that type should be supplied as the value of this option. 

rparser Specifies the function called to translate input strings into objects 
of the desired type. The function is called with one argument, the 
string entered by the user. 

This option is typically used when the set of possible completions is 
not known in advance, and can therefore not be enumerated. If they 
can be enumerated, use dw:complete-from-sequence or 
dw:completing-from-suggestions instead. 

The parser function is called on each possible completion string 
when a list of possibilities is generated, and on the user-supplied in- 
put when the completion utility is about to return a value. 

rcomplete-activates 

Boolean option specifying whether the COMPLETE key causes activa- 
tion, that is, whether the completion utility returns if a unique com- 
pletion was found. The default is nil. 

This option is used to control completion behavior in a multi-field 
input context, such as in the command processor. Normally, the END 
key performs completion and then returns if the resulting comple- 
tion is unique. 

rcompress-choices 

Specifies whether to compress the display of completion possibilities 
that have a common left token as defined by the rcompression- 
delimiter option. Three values are possible: 
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An integer 

When the possibilities exceed this number, the display is 
compressed. The default value is 20. 

ralways Whenever more than one possibility exists, the display is 
compressed. 

rnever The display is never compressed, regardless of the number 
of possibilities. 

Compressed displays have the form "token ... (n)", where token is the 
shared left token and n is the number of possible completions. 

To see an example of choice compression, press HELP to the com- 
mand processor prompt in a Dynamic Lisp Listener. You get the fol- 
lowing display (abbreviated for this example): 

You are being asked to enter a command or form. 
Use the Help : Format Detailed command to see a full 
list of command names. 

These are the possible command names: 
Add Paging File 
Append 
Clean File 
Clear ... (3) 
Close File 
Compare Directories 
Compile ... (2) 
Copy ... (5) 
Create ... (4) 
Debug Process 



"Add Paging File", "Append", and "Clean File" are full command 
names. "Clear" is a left token shared by three commands, Clear All 
Breakpoints, Clear Breakpoint, and Clear Output History. These 
three completion choices have been compressed to "Clear ... (3)". 
The user can expand this and other compressed choices by clicking 
on them with the mouse. 

rcompression-delimiter 

Specifies a character used for delimiting the shared left tokens in a 
display of completion possibilities. The default value is #\space. 

rinitially-display-possibilities 

Boolean option specifying whether to display the entire set of com- 
pletion possibilities before prompting for input; the default is nil. If 
t, the behavior is as if the user typed Help before any other input. 
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Most parsers should supply to this option the same value that was 
supplied to them by accept, accept, in turn, has an rinitially- 
display-possibilities option controlled by its caller. See the function 
accept. 

For an overview of dw:completing-from-suggestions and related facilities, see the 
section "Defining Your Own Presentation Types". 



(flavorrmethod rcompute-motion tvrsheet) string &optional (start 0) (end nil) x y 
cr-at-end-p (stop-x 0) stop-y Method 

Determines where the cursor would end up if you were to output string using 
:string-out. It does the right thing if you give it just the string as an argument. 
start and end can be used to specify a substring as with :string-out. x and y can 
be used to start your imaginary cursor at some point other than the present posi- 
tion of the real cursor. If you specify cr-at-end-p as t, it pretends to do a :line-out 
instead of a :string-out. stop-x and stop-y define the size of the imaginary window 
in which the string is being printed; the printing stops if the cursor becomes si- 
multaneously > both of them. These default to the lower left-hand corner of the 
window. 

The method does a triple-value return of the x and y coordinates you ended up at 
and an indication of how far down the string you got. This indication is nil if the 
whole string (or the part specified by start and end) was exhausted, or the index of 
the next character to be processed when the stopping point (end of window) was 
reached, or t if the stopping point was reached only because of an extra carriage 
return due to cr-at-end-p being t. 

All coordinates for this message are in pixels. 



dw:computing-outline-from-path f&optional (stream *standard-output*J &key 
.■transform) &body body Macro 

Returns a sequence of lines suitable for :highlighting-boxes corresponding to un- 
filled graphics drawn to stream by body, possibly with a transform specified by the 
keyword rtransform. For example: 

(dw:computing-outl ine-f rom-path (stream) 
(graphics :draw-ci rcle center-x center-y (+ radius 2) 

: stream stream : filled nil) 
(graphics :draw-ci rcle center-x center-y (- radius 2) 

: stream stream : filled nil)) 



(flavorrmethod rconfiguration tvrbasic-constraint-frame) Method 

Returns the symbol naming the current configuration of the frame. 
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(flavorrmethod rconfiguration tv:basic-constraint-frame) configuration-name 

Init Option 

Makes the initial configuration of the frame be the one named by the symbol con- 
figuration-name. 

(flavorrmethod rconfigurations tvrbasic-constraint-frame) configuration- 
specification-list Init Option 

Controls the sizes and arrangement of the panes in each possible configuration of 
a constraint frame. It is required for all flavors of constraint frames. 

In earlier releases, equivalent information was required to be specified under the 
rconstraints init option; it is still accepted for compatibility. See the section "Spec- 
ifying Panes and Constraints in Non-Dynamic Windows". To convert a rconstraints 
option to a rconfigurations option, see the function tvrback-convert-constraints. 

The value of the rconfigurations init option is an alist that associates configura- 
tion names with configuration specifications. Each configuration specification con- 
sists of a list of layout specifications and a list of size specifications. Thus the 
skeleton of a typical rconfigurations argument to tvrmake-window looks like: 

:conf igurations ' ((main-configuration 

(: layout spec spec.) 
(: sizes spec spec...)) 
(alternate-configuration 
(: layout spec spec.) 
(: sizes spec spec.))) 

The rlayout and rsizes clauses may appear in either order. 

A configuration arranges entities within the frame. Each entity has a name (a 
symbol). There are four kinds of entity: 

pane A window inferior to the frame. 

row A linear arrangement of entities, side by side. All the entities 

in a row are the same height. 

column A linear arrangement of entities, one above the other. All the 

entities in a column are the same width. 

fill An area that does not contain any windows, but is simply filled 

with some pattern. 

The entities in a row can be panes, fills, or columns. The entities in a column can 
be panes, fills, or rows. Rows and columns are collectively referred to as stacks. 
The subentities of a stack are referred to as the members of the stack. Different 
types of members can be mixed. 

Configuration specifications have certain restrictions. All names used in a configu- 
ration specification must be defined as entities exactly once within that specifica- 
tion. Each entity must be used as a member of a stack exactly once, except for the 
entity with the same name as the configuration, which must not be a member of 
any stack. No stack can contain itself, directly or indirectly. 
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tv:constraint-frame Flavor 

The basic kind of constraint frame. A frame of this flavor is built out of almost 
the same facilities as is tvrminimum-window; the frame does not have all the mix- 
ins that go into the tvrwindow flavor. In particular, it will not have any borders 
or a label. It also has tv:pop-up-notification-mixin as a component. 



tv:constraint-frame-with-shared-io-buffer Flavor 

Like tv:constraint-frame, but all the panes of the frame share the same I/O buf- 
fer used by the frame itself. However, the frame does not have tv:stream-mixin as 
a component, and it does not handle :any-tyi and :tyi messages. 

(tv:constraint-frame-with-shared-io-buffer is a component flavor of the Dynamic 
Window flavor dw:program-frame.) 



(flavorrmethod rconstraints tv:basic-constraint-frame) configuration-description- 
list Init Option 

Required for all flavors of constraint frames before Dynamic windows. It has been 
replaced by the rconfigurations init option. See the init option (flavorrmethod 
rconfigurations tvrbasic-constraint-frame). To convert a rconstraints option to a 
rconfigurations option, see the function tvrback-convert-constraints. 

The argument, configuration-description-list, is a list of configuration descriptions. 
For the format of configuration descriptions, see the section "Specifying Panes and 
Constraints in Non-Dynamic Windows". 



(flavorrmethod rconstraints tvrbasic-constraint-frame) Method 

Returns the configuration description list of the frame. 

dwrcontinuation-output-size continuation stream &optional (unit rpixel) Function 

Determines the amount of space a specified continuation would require for output 
on a specified stream. Six values are returned: width, height, cursor-motion-x, and 
cursor-motion-y , left, top. 

The continuation is funcalled with a single argument, an internal stream, which 
tracks the cursor motion caused by the output code of continuation. 

continuation 

The continuation to run. 

stream The output stream. This must be supplied, even though no output is 
actually sent to it, because information about the stream is neces- 
sary. For example, if a r string-length message is involved, the de- 
fault character style for the stream is needed information. 
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unit The unit of measure. The default is rpixel; the other possible value 

is rcharacter. 

Example: 

(def macro centering-about-point ((stream x y) &body body) 
1 (centering-about-point- internal 

(zl : named-lambda centering-about-point (, stream) ,@body) 
, stream , x , y)) 

(defun centering-about-point-internal (continuation stream x y) 
(multiple-value-bind (width height) 

(dw:continuation-output-size continuation stream) 
(let ((start-x (- x (round width 2))) 

(start-y (- y (round height 2)))) 
(dw: in-sub-window (stream start-x start-y width height) 

(funcall continuation stream)) 
;; Drawing the lines is just to verify the centering 
(graphics:draw-l ine start-x start-y (+ start-x width) 

(+ start-y height)) 
(graphics:draw-l ine (+ start-x width) start-y start-x 

(+ start-y height)) 
))) 

;;; Some code to test it 
(defun test-centering () 

(send xstandard-outputx : clear-window) 
(multiple-value-bind (left top right bottom) 

(send xstandard-outputx : visible-cursorpos-1 imits) 
(let ((center-x (round (+ left right) 2)) 
(center-y (round (+ top bottom) 2))) 
(centering-about-point (xstandard-outputx center-x center-y) 
;; Surround with border just to show 
;; the bounding box of the output 

(dw:surrounding-output-with-border (xstandard-outputx) 
; ; Generate some output 
(cp: execute-command "Show Flavor Handler" 

':tyo 'dw:dynamic-window 
:code : detailed)))) 
;; Drawing the lines is just to verify the centering 
(graphics:draw-l ine left top right bottom) 
(graphics:draw-l ine right top left bottom) 
; ; Pause to read a character before the command prompt 
;;clobbers our carefully crafted output, 
(read-char))) 
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; ; In a full-size Lisp Listener, try 

;; (with-character-size (:large) (test-centering)) 

For an overview of dw:continuation-output-size and related facilities: See the sec- 
tion "Writing Formatted Output Macros". 



(flavorrmethod :cr-not-newline-flag tvrsheet) x Init Option 

If x is 0, typing #\return will move the cursor position to the beginning of the 
next line and clear that line; if it is 1, typing #\return will display "return" in a 
lozenge (that is, #\return will be just like other special characters). It defaults to 
0. This flag does not affect the behavior of the :line-out nor the :fresh-line mes- 
sages. 

(flavorrmethod :current-font tvrsheet) Method 

Returns the current font, that is, the font used for NIL.NIL.NIL, as a font object. 
Example: 

(send xstandard-outputx : current-font) ==> 
#<F0NT CPTFONT 260000546> 



(flavorrmethod rcurrent-geometry tvrmenu) Method 

Returns a list of six elements that constitute the geometry corresponding to the 
actual current state of the menu. This contrasts with the rgeometry message, 
which returns the specified default geometry. Only the maximum width and maxi- 
mum height can be nil. 



dwrcurrent-program &key window (type 'dwrrprogramj (error-p t) Function 

Returns the current program of the type specified by rtype given the starting win- 
dow specified by rwindow. This useful for command translators that need to get to 
the program associated with the window in which you clicked. 



timerdaylight-savings-p Function 

Returns t if daylight savings time is currently in effect; otherwise, return nil. 

timerday-of-the-week-string day-of-the-week &optional {mode 'rlong) Function 

Returns a string representing the day of the week. As usual, means Monday, 1 
means Tuesday, and so on. Possible values of mode are: 
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rshort Return a three-letter abbreviation, such as "mon", "tue", and so on. 

:long Return the full English name, such as "monday", "tuesday", and so 
on. This is the default. 

rmedium Same as rshort, but use "tues" and "thurs". 

rfrench Return the French name, such as "lundi", "mardi", and so on. 

rgerman Return the German name, such as "montag", "dienstag", and so on. 

ritalian Return the Italian name, such as "lunedi", "martedi", and so on. 



(flavorrmethod rdeactivate tvrmenu) 



Method- 



Deactivates a window, deexposing it. In momentary menus, it is sent when the 
mouse is moved outside the borders of the menu. 



dw: dead-blip 



Flavor 



The error signalled when a mouse click goes unhandled. This is also the blip for- 
mat returned when an attempt to convert a mouse blip to a presentation blip fails. 
This flavor has instance variable mouse-char and component flavor condition 
Methods on this flavor include rreport. 



decode-universal-time universal-time &optional timezone 



Function 



Given a universal time, returns nine values for the corresponding decoded time: 
second (0-59); minute (0-59); hour (0-23); date (1-31); month (1-12); year (A.D.); day- 
of-week (0 [Monday] -6 [Sunday]); a flag (t or nil) indicating whether daylight sav- 
ings time is in effect; and the timezone (hours west of GMT). 



universal-time 
timezone 



Seconds, plus or minus, since midnight, January 1, 1900 GMT. 

Hours west (postive) or east (negative) of GMT; it defaults to 
the timezone set for the site (for more information: See the 
section "Specifying a Time Zone for Your Site".) Any real num- 
ber is allowed, but only numbers of the form n or n.5 can cor- 
respond to actual timezones. 



Examples: 
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(decode-universal-time 0) => 



19 

31 

12 

1899 

6 

NIL 

5 

(decode-universal-time 18000) => 



1 

1 

1900 



NIL 

5 

(decode-universal-time 0) => 



1 

1 

1900 



NIL 



time:decode-universal-time universal-time &optional timezone Function 

Converts universal-time into its decoded representation. The following values are 
returned: seconds, minutes, hours, date, month, year, day-of-the-week, daylight- 
savings-time-p. daylight-savings-time-p tells you whether or not daylight savings 
time is in effect; if so, the value of hour has been adjusted accordingly. You can 
specify timezone explicitly if you want to know the equivalent representation for 
this time in other parts of the world. Note that decode-universal-time is preferred 
for new code. 



(flavorrmethod : decode- variable-type tvrbasic-choose-variable-values) kwd-and- 
args Method 
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The system sends this message to a choose-variable-values window when it needs 
to understand an item, kwd-and-args is a list whose car is the keyword for the 
item and whose remaining elements, if any, are the arguments to that keyword. 
Six values are returned. The default method for : decode- variable-type looks for 
two properties on the keyword's property list: 

• tvrchoose-variable-values-keyword — The value of this property is a list of six 
values. 

• Unnecessary values of nil may be omitted at the end. 

• tvrchoose-variable-values-keyword-function — The value of this property is a 
function that is called with one argument, kwd-and-args. The function must re- 
turn the six values. 

Elements of the tvrchoose-variable-values-keyword Property 

The six elements of the tvrchoose-variable-values-keyword property are listed be- 
low. Note that if the specified list is shorter than six elements, the others default 
to nil. 

print-function 

A function of two arguments, object and stream, to be used to print the val- 
ue, prinl is acceptable. 

read-function 

A function of one argument, a stream, to be used to read a new value. 
zhread is acceptable. If nil is specified, there is no read-function and in- 
stead new values are specified by pointing at one choice from a list. If the 
read-function is a symbol, it is called inside an input editor, and over-rubout 
automatically leaves the variable with its original value. If read-function is 
a list, its car is the function, and it is called directly rather than inside an 
input editor. 

choices A list of the choices to be printed, or nil if just the current value is to be 
printed. 

print-translate 

If there are choices, and this function is supplied non-nil, it is given an ele- 
ment of the choice list and must return the value to be printed (for exam- 
ple, car for :assoc type items). 

value-translate 

If there are choices, and this function is supplied non-nil, it is given an ele- 
ment of the choice list and must return the value to be stored in the vari- 
able (for example, cdr for :assoc type items). 

documentation 

A string to display in the mouse documentation line when the mouse is 
pointing at this item. This string should tell the user that clicking the 
mouse changes the value of this variable, and any special information (for 
example, that the value must be a number). 
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Alternatively, the documentation element can be a symbol that is the name 
of a function. It is called with one argument, which is the current element 
of choices or the current value of the variable if choices is nil. It should re- 
turn a documentation string or nil if the default documentation is desired. 
This can be useful when you want to document the meaning of a particular 
choice, rather than simply saying that clicking on this choice selects it. 

Note that the function should return a constant string, rather than building 
one with zlrformat or other string operations. This is because it will be 
called over and over as long as the mouse is pointing at an item of this 
type. (The function is called by the mouse documentation line updating in 
the scheduler, not in the user process.) 



(flavorrmethod rdeexpose tvrmenu) Method 

Causes a menu to be deexposed. The window remains activated. This message is 
normally sent only by the system. It usually is meaningless if sent by a user pro- 
gram, because the window is exposed again immediately. 



(flavorrmethod rdeexposed-typein-action tvrsheet) Method 

Returns the deexposed typein action of the window. 

(flavorrmethod rdeexposed-typein-action tvrsheet) action Init Option 

Initializes the deexposed typein action of the window to action. This is the action 
taken when typein is required and the window is not exposed. The possibilities are 
mormal and motify. The default is mormal. 

(flavorrmethod rdeexposed-typeout-action tvrsheet) Method 

Returns the deexposed typeout action of the window. 

(flavorrmethod rdeexposed-typeout-action tvrsheet) action Init Option 

Initializes the deexposed typeout action of the window to action. This is the action 
taken when typeout is attempted and the window is not exposed. The possibilities 
are mormal, rerror, rpermit, rexpose, and motify, or a list of messages and mes- 
sage arguments. The default is mormal. 

cprr*default-blank-line-mode* Variable 

The default Command Processor blank line mode for cprread-command and 
cprread-command-or-form. This is a keyword that determines what action the 
Command Processor takes when you type a blank line: 
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rreprompt Redisplay the prompt, if any. This is the default. 

:beep Beep. 

rignore Do nothing. 

The blank line mode used in Lisp Listeners and zlrbreak loops is the value of 
cp : *blank-line-mode* . 

(flavorrmethod :default-character-style tvrmenu) character-style Init Option 

Specifies the default character style of the menu. Items whose character style is 
unspecified are displayed in the default style. If a character style is specified for 
an item, it is merged against the default style. (See the section "Menu Item Op- 
tions".) 

(flavorrmethod rdefault-character-style tvrsheet) character-style Init Option 

Specifies the character style for character output to the window. The default style 
is inherited from the screen (and is settable via the Set Screen Options command); 
the initial default character style is (:fix : roman : normal). To change a window's 
default style, use the : set-default-style method. See the method (flavorrmethod 
rset-default-character-style tvrsheet). 

For more information on character styles: See the section "Character Styles". 

cpr*default-command-accelerator-echo* Variable 

Controls whether accelerated commands are echoed (full command name) on the 
command line when their single-key accelerators are pressed. It is initially bound 
to t. 



dwrdefault-command-top-level program &rest options &key (window-makeup 
#'dwrrdefault-window-wakeup-handler) &allow-other-keys Function 

The default command loop function for programs created with dwrdefine-program- 
framework. 

program The program instance. (This argument is supplied by dwrdefine- 
progr am-f r amework) . 

rwindow-wakeup 

Specifies the function used by the program for handling asyn- 
chronous events (for example, when the user presses REFRESH or re- 
sizes the program frame). For an example:see the section "Handling 
Asynchronous Window System Events". 

In addition to rwindow-wakeup, the following keyword options are available: 
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rstream Specifies the stream for program command I/O; the default is 
*query-io*. 

rprompt Specifiesthecommandprompt.Thedefaultisastringconsistingof 

the name of your program followed by the word "command" and a 
colon, that is, "<Program-name> command:" 

:dispatch-mode 

Specifies the Command Processor dispatch mode, one of rcommand- 
only, rcommand-preferred, :form-only, or :form-preferred. (See 
the function cp:read-command-or-form.) 



cp::*default-dispatch-mode* Variable 

The default Command Processor dispatch mode for cp:read-command-or-form; a 
keyword. Possible values are :form-only, :form-preferred, :command-only, and 
rcommand-preferred. For the meanings of these values: See the section "Setting 
the Command Processor Mode". The default is rcommand-preferred. 

The dispatch mode used in Lisp Listeners and zlrbreak loops is the value of 
cpr*dispatch-mode*. 



tvrdefaulted-multiple-menu-choose alist defaults &optional near-mode Function 

alist is a list of lists of menu items. The form of a menu item can be one of: 

atom 

(something atom) 
(something . atom) 
(something : value atom) 
(something :eval 'atom) 
(something :eval atom) 

where in each case but the last atom is the item returned if selected in the menu. 
(In the last case the value of atom is returned.) See the section "The Form of a 
Menu Item". Each sublist corresponds to a column. 

defaults is a list of menu values, one for each column, which are initially high- 
lighted. 

This function is similar to tvrmultiple-menu-choose but the defaults received by it 
and the values returned by it are values, not items. For an example, see the sec- 
tion "tvrmultiple-menu-choose Example". 



cprr*default-prompt* Variable 

The default Command Processor prompt option for cprread-command and cprread- 
command-or-form. The value of this variable is passed to the input editor as the 
value of the rprompt option. The value can be nil, a string, a function, or a sym- 
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bol other than nil (but not a list): See the section "Displaying Prompts in the In- 
put Editor". The default is "Command: ". 

The prompt used in Lisp Listeners and zlrbreak loops is the value of cpr*prompt*. 
cprdefine-command name-and-options arguments &body body Macro 

Defines a Command Processor command. This important macro has many features 
and options. Its complete definition is contained in the chapter explaining its use, 
"Managing the Command Processor". See the function cprdefine-command. 



cprdefine-command-accelerator name command-table characters options arglist 
&body body Function 

Defines single-key accelerators for Command Processor commands. 

name Name for this accelerator. 

command-table 

Command table in which command and accelerator are included. 

characters A character or list of characters (not necessarily more than one) 
serving as the single-key accelerators. Prefix character sequences 
are also allowed, for example, ((#\c-x #\c-f)). 

options List of keyword-value pairs. Possible keywords include: 

rargument-allowed 

Boolean option specifying whether this accelerator is al- 
lowed to take numeric arguments (for example, c-3). The 
default depends on whether you provide an arglist, t if 
you do, nil if you don't. 

ractivate Boolean option specifying whether the command defined 
by this accelerator executes immediately when the acceler- 
ator is typed; the default is t. If nil, the command re- 
quires confirmation and, possibly, additional args. 

recho Boolean option specifying whether the command defined 
by this accelerator echoes on the command line as if it 
were typed. The default is the value supplied to the 
ractivate option; this is because in the : activate nil 
case, the command is visible after you are finished editing 
and need not be repeated. 

arglist List of arguments to the accelerated command. If rargument- 
allowed is nil, this arglist should be nil (no arguments allowed). 

If rargument-allowed is t, the accelerator receives two arguments, 
arg-p and arg. arg-p means whether or not the user gave an argu- 
ment to this accelerator; arg is the numeric arg. arg-p has several 
special keyword values. These are rsign, rdigits, rcontrol-u, and 
rinfinity. The arglist is typically just (arg-p arg), but you can put 
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anything here you want. This is just so that your body can make 
reference to these symbols under the names you chose. 

body A form that returns a command. It can make reference to the sym- 

bols bound in arglist. 

A typical body might be: 

1 (si : corn-del ete-f ile , (list path))) 

For an overview of cprdefine-command-accelerator and related facilities: See the 
section "Managing the Command Processor". 



cp:define-command-and-parser name-and-options arglist parser &body body 

Function 

Defines a Command Processor command and command line parser. 

name-and-options 

Either the symbol to be used as the command name or a list whose 
first element is the name symbol and succeeding elements are alter- 
nating keyword-value pairs. To distinguish command names from 
other kinds of names, we recommend that the prefix com- be used; 
the user-visible command name will not include the prefix. 

Permissible keywords are the same as those listed under name-and- 
options in the dictionary entry for cprdefine-command. 

arglist The argument list of the function that implements the body of the 
command. It is a normal, Common Lisp argument list. 

parser A form used to parse the command's arguments. This form has lexi- 
cal access to the internal functions cprread-command-argument, 
cprread-keyword-arguments, and cprassign-argument-value. It 

should use these functions to do the actual reading and assigning of 
values to command arguments: 

cprread-command-argument presentation-type &rest options 

A fletted function within cp:define-command-and-parser. 

presentation-type is the type of the argument, options are 
all options acceptable in a command argument specifica- 
tion to cprdefine-command. 

cprread-keyword-arguments &rest keyword-specs 

A macroletted macro within cprdefine-command-and- 

parser. keyword-specs are command argument specifica- 
tions identical to those you would use if you were writing 
the command using cprdefine-command. Even if there 
are no keyword arguments, the parser should end with 
cprread-keyword-arguments; any automatically generated 
keywords (for example, routput-destination) can thereby 
be read. 
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cp:assign-argument-value argument-name value 

A macroletted macro within cp:define-command-and- 

parser. Argument-name is a symbol naming a command 
argument; value is its value. Each argument-name should 
correspond to an argument in arglist above. 

Example: 

(cp : def i ne-command ( com- th i s-i s-a- test 
: command-table 'user) 
((file 'pathname : default nil : prompt "file") 
&key 
(integer 'integer :default 17 

:mentioned-defaul t 3 :prompt "the number")) 
(loop for i from to integer do 
(print file))) 

; ; ; is equivalent to 

(cp:def ine-command-and-parser (com-thi s-i s-a- test 
: command-table 'user) 

The arglist of the function. 
Note the presence (and need for) the 
default value for INTEGER in the 
argument list, 
(file &key (integer 17)) 

;; The argument parser. It's just one big PROGN. 
;; Note that it ends with read-keyword-arguments, 
(progn (cp: : assign-argument-value file 

(cp: : read-command-argument 'pathname 
: default nil : prompt "file")) 
(cp: : read-keyword-arguments 
(integer 'integer :default 17 

:mentioned-defaul t 3 :prompt "the number"))) 

;; The body of the command. 

(loop for i from 1 to integer do (print file))) 

To see other examples, try macroexpanding some cprdefine-command definitions; 
they expand into cp:define-command-and-parser definitions. 

For an overview of cp:define-command-and-parser and related facilities: See the 
section "Managing Your Program Frame". 



dw:define-command-menu-handler (command-name command-table menu-levels 
&key (.-gesture rleftj (-documentation t) .-tester) arglist &body command-form Macro 
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Defines a menu handler for the command named command-name in command-table 
for menu-levels. That is, defines a function that executes command-form with the 
arguments in arglist when the user clicks the mouse as specified by rgesture. com- 
mand-form should return a command, just as define-presentation-to-command- 
translator does. 

command-name 

A string, which identifies the item, and which is how it is normally 
displayed. 

command-table 

The command table into which to install the handler. It is normally 
a string, but can be anything that cp:find-command-table under- 
stands, including a symbol. 

menu-levels 

A list of keywords naming the menu levels in which the handler 
should appear. The same handler can be in more than one menu 
level. Normally, of course, menus for both levels would never be on 
the screen at the same time in this case. 

gesture A single keyword, or list of keywords, identifying which gestures 
this handler applies to. A single handler can apply to more than one 
gesture, and multiple handlers can be defined on different gestures. 
The possible actions will then naturally be their union. 

documentation 

Similar to the documentation for define-presentation-to-command- 

translator. It can be a fixed string or a list of arguments and body 
to produce such a string. Additionally, it can be t, meaning run the 
command-form to produce the desired command and use it for the 
documentation. This is the default. 

tester Similar to the tester for define-presentation-to-command- 

translator. It is a function name (symbol) or list of arguments and 
body to define such a function. The function is run to determine 
whether the handler is available. 

arglist (start with &key): 

Contrary to the case of 

define-presentation-to-command-translator, there is no initial pre- 
sentation object argument. The keywords passed to as this arglist 
are :menu-level and rgesture, specifying how the handler was in- 
voked, and rwindow, giving the menu from which the presentation 
was taken. 

Normally, a command menu handler calls dw:standard-command-menu-handler, 
which takes a command name and arguments as passed to the command form of 
dw:define-command-menu-handler and does the standard actions for two mouse 
gestures. 
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For an overview of how command menus work and several examples of the use of 
dw:define-command-menu-handler: See the section "How Command Menus Work". 



define-cp-command name args &body body Function 

The pre-Genera 7.0 facility for defining Command Processor commands. Currently, 
the recommended command-definition facility is cprdefine-command. For an 
overview of the latter and related facilities: See the section "Managing the Com- 
mand Processor". 

Code that defines commands with the obsolete define-cp-command macro still 
works, but the compiler will suggest that you change the syntax of any old-style 
argument type specifiers (for example, rpathname) to presentation type specifiers 
(for example, 'pathname) — in fact, it will make that change for you. Note: You 
can no longer use user-defined old-style type-specifiers. These will not compile. 

define-cp-command defines a Command Processor command, name is a specifica- 
tion for the command name, args is a specification for the command arguments. 
define-cp-command defines a function that executes the command, with body as 
the body of the function. The name of the function is derived from name and the 
arguments from args. 

name is a symbol or a list. If name is a symbol, it is the name of the function that 
executes the command. By convention, the first four characters of the symbol's 
print name are usually "COM-". 

If name is a list, the first element is a symbol, the name of the function that exe- 
cutes the command. The remaining elements are alternating keywords and values. 
Each keyword-value pair is optional. Following are the permissible keywords and 
values: 

:name A string that represents the command name that the user 

types. If this option is not specified, the name is the result of 
calling zhstring-capitalize-words on the symbol's print name, 
except that if the symbol's print name begins with "COM-", 
those characters are omitted from the command name. This op- 
tion is useful for special capitalization of words, as in "Start 
GC". 

rcomtab A command table or a string naming a command table in 

which to install the command. For example, to install a com- 
mand in the "User" command table, you might specify "User" 
or the result of (sirfind-comtab "user"). This option is evalu- 
ated. If it is not specified, the command is not installed in any 
command table and cannot be read. See the section "Command 
Processor Command Tables". 

args is nil or a list of argument specifications for the arguments to the command 
and the function that executes the command. One element of args can be the sym- 
bol &key instead of an argument specification. All argument specifications preced- 
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ing &key denote positional arguments to the command. All argument specifications 
following &key denote keyword arguments to both the command and the function 
that executes the command. 

An argument specification is a list that describes one argument to the command. 

The first element of an argument specification is a symbol. This symbol names a 
parameter in the arglist of the function that executes the command. This parame- 
ter is bound to the value of the argument when the function is called to execute 
the command, body can refer to the parameter. Unless a :name option is supplied 
later in the argument specification, the user-visible name of the argument is the 
result of calling zlrstring-capitalize-words on the symbol's print name. 

The second element of an argument specification is an argument type specification. 
This is a keyword or a list. If it is a keyword, it is the name of this argument's 
type. If it is a list, the first element is a keyword that is the name of this argu- 
ment's type. The remaining elements supply information specific to the argument 
type. See the section "Command Processor Argument Types". 

The remaining elements of an argument specification are alternating keywords and 
values. Each keyword-value pair is optional. None of the values is evaluated. Fol- 
lowing are the permissible keywords and values: 



: allow-multiple 



t if the argument can have multiple values; nil if the argu- 
ment can have only one value. The user enters multiple values 
as a series separated by commas. These are passed to the com- 
mand function as a list of values. The default is nil. 



rconfirm 



: default 



t if the argument requires confirmation by the user; nil if it 
does not. The default is nil. 

A form to be evaluated when the argument is read to return 
the default value for the argument. If : allow-multiple is speci- 
fied with a value of t, the form must return a list of values. 
The form can refer to parameters defined for any positional ar- 
guments (but not keyword arguments) specified in args before 
this argument specification. At the time the form is evaluated, 
these parameters are bound to the values of arguments already 
read. 

For a positional argument, if rdefault is not supplied the argu- 
ment has no default value. When the command is read, the 
user is forced to supply a value. 

For a keyword argument, the default used depends on what 
combination of rdefault and rmentioned-default options is 
supplied: 



Both 



Use the rmentioned-default default if the 
user types the name of the argument; oth- 
erwise use the rdefault default. 
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rmentioned-default only 

If the user types the name of argument, 
use the rmentioned-default default. Other- 
wise the default is nil. 

rdefault only Use the rdefault default. 

Neither If the user does not type the name of the 

argument, the default is nil. If the user 
types the name of the argument, the argu- 
ment has no default value, and the user is 
forced to supply a value. 

rmentioned-default For a keyword argument, a form to be evaluated when the ar- 
gument is read to return the default value if the user types 
the name of the argument. If rallow-multiple is specified with 
a value of t, the form must return a list of values. The form 
can refer to parameters defined for any positional arguments 
(but not keyword arguments) specified in args before this argu- 
ment specification. At the time the form is evaluated, these pa- 
rameters are bound to the values of arguments already read. 

The default used depends on what combination of rdefault and 
rmentioned-default options is supplied: 

Both Use the rmentioned-default default if the 

user types the name of the argument; oth- 
erwise use the rdefault default. 

rmentioned-default only 

If the user types the name of argument, 
use the rmentioned-default default. Other- 
wise the default is nil. 

rdefault only Use the rdefault default. 

Neither If the user does not type the name of the 

argument, the default is nil. If the user 
types the name of the argument, the argu- 
ment has no default value, and the user is 
forced to supply a value. 

Use this option when you want the default to depend on 
whether or not the user types the argument name. For exam- 
ple, the Delete File command has an :Expunge keyword argu- 
ment whose rdefault default is No and whose rmentioned- 
default default is Yes. 

ruse-type-default If non-nil, the default for this argument is determined by the 
current default for this type of argument, for example, a path- 
name for commands that deal with files. The default is t. 
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:set-type-default 



: documentation 



:name 



rprompt 



If non-nil the default for this argument becomes the current 
default for this type of argument (for example, a pathname for 
commands that deal with files). The default is t. 

A string, usually short, that documents the meaning of the ar- 
gument. The string is displayed after the argument name if 
the user presses HELP while entering the argument. For exam- 
ple, the string for the argument to the Show Hosts command 
is "Hosts about which to display status information". The de- 
fault HELP display depends on the argument type. 

A string that represents the user-visible name of the argu- 
ment. The default name is the result of calling zhstring- 
capitalize-words on the print name of the symbol that is the 
first element of the argument specification. This option is use- 
ful when you want the user-visible name of the argument to 
differ from the parameter bound to the argument value. For 
example, you might want the user-visible name to be Base 
without binding the special variable zhbase. 

A string that represents a prompt for the argument, or a form 
to be evaluated when the command is read to return a prompt 
string. The form is evaluated with the symbol =default= bound 
to the argument default. =default= is interned in the package 
that is the value of zhpackage when the define-cp-command 
form is evaluated. The default prompt depends on the argu- 
ment type. See the section "Command Processor Argument 
Types". 



Example: 

(define-cp-command (com-edit-f ile :comtab "Global") 
((file : pathname 

:al low-multiple t 

: def aul t ' ( , (f s : def aul t-pathname) ) 

: prompt 

(format nil "file to edit [default 

: documentation "Files to edit")) 
(ed file) 

(send standard-output : fresh-line) 
(send standard-output :tyo #\newline) 
(values)) 



~A]" (first =default=)) 



define-presentation-action name (from-presentation-type Macro 

to-presentation-type &key tester (gesture rselect) documentation 
suppress-highlighting (menu t) (context-independent nil) priority 
exclude-other-handlers blank-area defines-menu) arglist &body body 

Defines a side-effecting mouse handler for performing actions on a displayed pre- 
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sentation object that are independent of the main body and command loop of an 
application. The complete description of this macro is containted in the chapter 
"Programming the Mouse: Writing Mouse Handlers". 

define-presentation-to-command-translator name Macro 

(presentation-type &key tester (gesture rselect) documentation 
suppress-highlighting (menu t) (context-independent nil) priority 
exclude-other-handlers blank-area do-not-compose) arglist &body body 

Defines a mouse handler that translates from a displayed presentation object into a 
Command Processor command using that object as input. The complete description 
of this macro is contained in the chapter "Programming the Mouse: Writing Mouse 
Handlers". 



zwei:define-presentation-to-editor-command-translator name (type echo-name 
comtab &rest options &key .-gesture .-tester &allow-other-keys) (object &rest other- 
args) &body body Macro 

Returns the list of a function name and argument values that calls an editor com- 
mand function. The function need not be defined with zweirdefcommand. The 
function should return nil if the typeout window should be flushed, or non-nil if 
the typeout window should be left alone. 

name The name of the command. 

type The from-presentation type. 

echo-name A string to echo when the mouse is clicked. 

comtab A symbol whose value is the command table that determines 

whenter the translator is available. Only if commands in that 
command table are available is this translator available. This 
is typically zwei:*standard-comtab* or zwei:*zmacs-comtab* 
or it could be your own command table. 

The remaining arguments are the same as those of define-presentation-to- 
command-translator. See the function define-presentation-to-command- 
translator. 

Example: 

(defun show-length-of-pl ist (symbol) 

(zwei : typein-1 ine "~D" (length (symbol -pi ist symbol)))) 

(zwei :def ine-presen tat ion- to-edi tor-command- translator 

show-1 ength-of-pl i st 
(symbol "PI ist length" 
zwei :*standard-comtabx 
: gesture : super-middle) 
(symbol ) 
' (show-length-of-pl ist , symbol)) 
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define-presentation-translator name (from-presentation-type Macro 

to-presentation-type &key tester (gesture rselect) documentation 
suppress-highlighting (menu t) (context-independent nil) priority 
exclude-other-handlers blank-area do-not-compose) arglist &body body 

Defines a mouse handler that translates from a displayed presentation object of a 
certain type to a returned presentation object of a different type. The complete de- 
scription of this macro is contained in chapter "Programming the Mouse: Writing 
Mouse Handlers". 

define-presentation-type type-name (data-arglist . pr-arglist) Macro 

&key parser printer view spec-choices description describer no-deftype 
disallow-atomic-type (history nil history-supplied-p) expander 
abbreviation-for choose-displayer accept-values-displayer 
menu-displayer default-preprocessor history-postprocessor 
highlighting-box-function presentation-type-arguments 
presentation-subtypep key-generator key-function do-compiler-warnings 
map-over-subtypes map-over-supertypes 
map-over-supertypes-and-subtypes typep with-cache-key 
(data-arguments-are-disjoint t) 

Defines a presentation type. The full description of this macro is contained in a 
chapter of its own. See the section "Defining Your Own Presentation Types". 



dwrdefine-program-command (name program-name &rest options &key (keyboard- 
accelerator nil) (menu-accelerator nil) (menu-level '(:top-level)J (menu-documentation 
t) menu-documentation-include-defaults provide-output-destination-keyword &allow- 
other-keys) arglist &body body Function 

Defines a Command Processor command for a program created with dwrdefine- 
program-framework and installs it in the program's command table. The defini- 
tion generates two internal methods for the program flavor, one to parse the com- 
mand and one to execute the command. These methods provide lexical access to 
your program's state variables both in the body of the command definition and in 
the command argument list; that is, you may use state variables as arguments. 

name The name given to the command. To distinguish command names 
from other kinds of names, we recommend that the prefix com- be 
used, for example com-exit-program. The user-visible command does 
not include the prefix; in the above example, the user-visible com- 
mand is Exit Program. 

Like other commands, those you define using dwrdefine-program- 
command occupy the function namespace. 

program-name 

The symbol or string naming the program flavor (created by 
dwrdefine-program-framework) for which the command is being 
written. This is also the name of the program's command table. 
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rkeyboard-accelerator 

Specifies the key used to invoke the command; the default is nil. 
For example, if you are writing an Exit Program command, you 
might wish to specify #\E as the keyboard accelerator. 

This option may not be used if nil is specified for the :kbd- 
accelerator-p option to the :command-table keyword for dwrdefine- 
program-framework. See the function dwrdefine-program- 
framework 

:menu-accelerator 

Specifies whether the command identifier is displayed in a command 
menu pane for the program; the default is nil. 

To make the command available in a menu, supply a value of t or a 
string, t causes the user-visible name of the command to be dis- 
played. If you provide a string, it is displayed instead of the user- 
visible name. 

Note that the program frame must include a pane of the 
:command-menu type in order for the command identifier to be 
displayed. See the function dwrdefine-program-framework. 

:menu-level 

Specifies the command menu in which the command is to be dis- 
played. You need to use this option explicitly only when more than 
one command menu pane has been specified in the dwrdefine- 
program-framework macro for your program. (See the function 
dw: def ine-progr am-f r amework. ) 

rmenu-documentation 

Specifies documentation to be displayed in the mouse documentation 
line when the mouse is over the command in the command menu. 

rmenu-documentation can be either a string, which is the docu- 
mentation, or it can be a function that takes rwindow, rgesture, 
rmenu-level, and rarguments as keyword arguments and either re- 
turns a string or a command-structure (as in ' (si :com-show-f ile 
,foo)). If a command-structure is returned it is unparsed to produce 
the documentation. 

Examples: 

(dw:def ine-program-f ramework MD 
: select-key #\! 
: panes ((display : display) 

(menu : command-menu) 

(interactor : interactor)) 
:command-def iner t) 
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(def ine-MD-command (com-test-1 : menu-accelerator t 

: menu-documentati on 
"This is the MD command") 
((integer 'integer)) 
(print integer)) 

(def ine-MD-command (com-test-2 :menu-accelerator t 

: menu-documentati on 
((&rest ignored) 
1 (com-test-1 ,3))) 

0) 

:menu-documentation-include-defaults 

Specifies, when t, that the defaults for this command should be pre- 
sented in the mouse documentation line. 

Compare what happens when you move the mouse over Test 3 and 
Test 4. The mouse documentation for Test Four is "Test 4 7" (or 
whatever the last integer you typed to the Test 4 command was) 
while the mouse documentation for Test 3 is just "Test 3". 

(dw:def ine-prog ram- framework MDID 
: select-key #\~ 
: panes ((display : display) 

(menu : command-menu) 

(interactor : interactor)) 
:command-def iner t) 

(def ine-MDID-command (com-test-3 :menu-accelerator t) 
((integer 'integer)) 
(print integer)) 

(def ine-MDID-command (com-test-4 :menu-accelerator t 
: menu-documentati on- include-defau Its t) 
((integer 'integer)) 
(print integer)) 

rprovide-output-destination-keyword 

Boolean option specifying whether to provide the routput- 
destination keyword. The default is nil (unlike 
cprdefine-command). This option allows the user of the command 
to redirect the output of the command to a place other than the 
screen. 

Additional keyword options to dwrdefine-program-command are the same as 
those documented under name-and-options in the Dictionary entry for 
cprdefine-command. These include rcommand-table, rexplicit-arglist, 
rprovide-output-destination-keyword, and rvalues. 
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arglist The list of command arguments. Each element of the list is itself a 
list of the form (arg-name presentation-type options) where arg-name 
is the name of the argument; presentation-type is the presentation- 
type of the argument; and options are keyword options to the argu- 
ment. 

Permissible options are the same as those documented under argu- 
ments in the description of cprdefine-command in "Managing the 
Command Processor". These include : documentation, rprompt, 
:prompt-mode, rdefault, rmentioned-default, :when, :name, 
:default-type, rprovide-default, rdisplay-default, and rconfirm. 

For an overview of dwrdefine-program-command and related facilities, see the 
section "Defining Your Own Program Framework". 

dwrdefine-program-framework name &key pretty-name Macro 

(command-definer nil) (command-table nil) (top-level (quote 
(dw:default-command-top-level))) (command-evaluator nil) (panes 
(quote (dw::main rlistener))) selected-pane query-io-pane 
terminal-io-pane label-pane (configurations nil) (state-variables nil) 
(selectable t) (select-key nil) (system-menu nil) (size-from-pane nil) 
(inherit-from (quote (dw::program))) (other-defflavor-options nil) 

Defines a program framework. The complete definition of this macro is included in 
its own chapter. See the section "Defining Your Own Program Framework". 

define-prompt-and-read-type keyword parameter-list description &body body 

Function 

This function is obsolete. New types should be defined with define-presentation- 
type. 

define-prompt-and-read-type defines a new type keyword for prompt-and-read, 
and a dispatch function to be called to get input from the user when prompt-and- 
read is called with a type keyword of keyword. The dispatch function is defined as 
the prompt-and-read property of keyword, which can be a symbol in any package. 
Its parameter list is derived from parameter-list, and its body is body, prompt-and- 
read returns whatever the dispatch function returns. 

If the first argument to prompt-and-read is just keyword, the dispatch function is 
called with no arguments. If the first argument to prompt-and-read is 
(keyword . type-args), the arguments to the dispatch function are the elements of 
type-args. These are a series of alternating keywords and values. 

parameter-list is nil if no type-args are allowed, or else a list of &key elements for 
the dispatch function's parameter list, define-prompt-and-read-type inserts &key 
in the parameter list itself; &key should not appear in parameter-list. 

description can be nil, a zhformat control string, a list of a zhformat control 
string and zhformat control args, or a form to be evaluated, description is used to 
generate input-type in the default prompt, "Enter input-type: ": 
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description input-type 

nil "a " followed by the print name of the type keyword. 

zhformat control string 

Generated by calling zhformat with arguments of t and the 
control string when it is time to display the prompt. 

list of zhformat control string and args 

Generated by calling zhformat with arguments of t, the con- 
trol string, and the control args when it is time to display the 
prompt. The control args can examine any of the parameters in 
parameter-list. 

form Generated by evaluating the form when it is time to display 

the prompt. The form can examine any of the parameters in 
parameter-list. It should send output to zhstandard-output. 

body is the body of the dispatch function. Often the body is a call to a more primi- 
tive reading function, such as zhread or zhreadline. It is the responsibility of the 
body or a function it calls to provide input editing if needed. 

Example: 

(def i ne-prompt-and-read-type : f 1 avor-name 

((impossible-is-ok t)) 

"the name of a flavor" 

(sys: read-flavor-name query-io impossible-is-ok)) 

sys:read-flavor-name is a function that reads a flavor name with completion over 
the set of defined flavors. 



define-user-option (option alist) default [type] [name] Function 

(define-user-option (option alist) default type name) defines the special variable op- 
tion to be an option in the alist, which must have been previously defined with 
define-user-option-alist. The variable is declared and initialized via (defvar option 
default). The value of the form default is remembered so that the variable can be 
reset back to it later. 

type is the type of the variable for purposes of the choose-variable-values facility. 
It is optional and defaults to :sexp. 

name is the name of the variable to be displayed in the choose-variable-values 
window. It is optional and defaults to a string that is the print-name of the vari- 
able except with hyphens changed to spaces and each word changed from all- 
upper-case to first-letter-capitalized. If the first and last characters of the print- 
name are asterisks, they are removed. For example, the default name for 
so:*sunny-side-up* would be "Sunny Side Up". 



define-user-option-alist name [constructor] Function 
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(define-user-option-alist name) defines name to be a global variable whose value 
is a "user option alist", something which may be used by the other functions be- 
low. This alist keeps track of all of the option variables for a particular program. 

(define-user-option-alist name constructor) also specifies the name of a constructor 
macro to be defined, which provides a slightly different way of defining an option 
variable from define-user-option. The form (constructor option default type name) 
defines an option in this user-option-alist. The arguments are the same as to 
define-user-option. 



tvrdef window-resource name parameters &rest options Function 

Defines a resource of windows, name is the name of the resource, parameters is a 
lambda-list of parameters to defresource. options are alternating keywords and 
values: 

Keyword Value 

rinitial-copies Number of windows to be created during evaluation of 

defresource form. Default: 1. 

rsuperior A form to be evaluated when the resource is allocated to re- 

turn the superior window of the desired window. If this is 
not supplied, the superior is the value of tv:mouse-sheet. 

rmake-window List of flavor name and options to tvrmake-window, which 

will be called to make new windows. One of the options can 
be rsuperior. 

rconstructor A form or the name of a function to make new windows. You 

must supply either rmake-window or rconstructor. 

rreusable-when Either rdeexposed or rdeactivated. Specifies when a window 

can be reused. Supply this when you use allocate-resource 
without a mtaching deallocate-resource instead of using- 
resource to allocate resources. Default: reusable when not 
locked and not in use. 

tvrdef window-resource also accepts any of the keywords from defresource. 
tvrdef window-resource handles its own keywords and defresource's rchecker key- 
word, and any others it passes to defresource. 



tvrdelayed-redisplay-label-mixin Flavor 

Adds the rdelayed-set-label and rupdate-label messages to your window. You send 
a rdelayed-set-label message to change the label in such a way that it will not ac- 
tually be displayed until you send an rupdate-label message. This is especially use- 
ful for programs that suppress redisplay when there is typeahead; the user's com- 
mands may change the label several times, and you may want to suppress the re- 
display of the changes in the label until there isn't any typeahead. 
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(flavorrmethod :delayed-set-label tv:delayed-redisplay-label-mixin) specification 

Method 

Like the :set-label method, except that nothing actually happens until an rupdate- 
label message is sent. 



(flavorrmethod :delayed-set-label dwrmargin-mixin) new-label Method 

Provides a new label for a Dynamic Window, but delays the writing of the new la- 
bel until the rupdate-label message is sent: See the method (flavorrmethod 
rupdate-label dwrmargin-mixin). See the method (flavorrmethod rset-label 
dwrmargin-mixin). 

new-label The new label, which can be either a string or t, which specifies 
that the window's name is to be the label, or a list of options to 
dwrmar gin-label. 

For an overview of (flavorrmethod rdelayed-set-label dwrmargin-mixin) and relat- 
ed facilities: See the section "Window Substrate Facilities". 



tvrdelaying-screen-management Function 

The tvrdelaying-screen-management special form just has a body: 
(tv : del ayi ng-screen-management 
form-1 
form-2 

The forms are evaluated sequentially with screen management delayed. The value 
of the last form is returned. 



(flavorrmethod rdelete-char tvrsheet) &optional {char-count 1) {unit 'rcharacter) 

Method 

Without an argument, deletes the character at the current cursor position. Other- 
wise, deletes char-count units, starting at the current cursor position. Moves the 
display of the part of the current line that is to the right of the deleted section 
leftwards to close the resultant gap. If unit is rcharacter, char-count is interpreted 
as the number of characters to delete; if unit is rpixel, char-count is interpreted as 
the number of pixels to delete. 



cprdelete-command-table command-table-or-name Function 

Removes a Command Processor command table from the command table registry. 

command-table-or-name 

A command table object or the name (symbol or string) of a com- 
mand table. 
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For an overview of cp:delete-command-table and related facilities: See the section 
"Managing the Command Processor". 



(flavorrmethod rdelete-displayed-presentation dw: dynamic- window) displayed- 
presentation Method 

Deletes an already displayed presentation from a Dynamic Window's output history 
and display. This method does not immediately affect the display, nor does it re- 
move associated text from the screen; use dwrerase-displayed-presentation to do 
these. 

displayed-presentation 

The presentation to delete. 

For an overview of (flavorrmethod rdelete-displayed-presentation dwrdynamic- 

window) and related facilities, see the section "Presenting Formatted Output". Ex- 
ample: 

(defun del ete-displayed-presentati on-test () 
(let ((presentation (dw:with-output-as-presentation (:type 'sys: expression 

:object 'test) 
(princ "test object")))) 
(format t "~&Click on presentation") 
(read) 

(send xstandard-outputx : del ete-displayed-presentati on presentation) 
(format t "~&No no longer sensitive.") 
)) 



(flavorrmethod rdelete-item tvrtext-scroll-window) item-no Method 

Deletes the item whose number is item-no. 

If the item being deleted was visible, the window redisplays to show the new state 
of the item list. 



(flavorrmethod rdelete-line tvrsheet) &optional (line-count 1) (unit 'rcharacter) 

Method 

Without an argument, delete the line that the cursor is on. Otherwise deletes line- 
count units, starting with the one the cursor is on. Moves up the display below the 
deleted section to close the resulting gap. If unit is rcharacter, line-count is inter- 
preted as the number of lines to delete; if unit is rpixel, line-count is interpreted 
as the number of pixels to delete. 



dwrdelete-presentation-mouse-handler name Function 

Removes an already defined presentation mouse handler. 
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name The name of the mouse handler to remove. 

For an overview of dw:delete-presentation-mouse-handler and related facilities: 
See the section "Programming the Mouse: Writing Mouse Handlers". 



dw:delete-presentation-type type-name Function 

Deletes presentation type type-name from the type hierarchy. Note that the system 
will not let you delete presentation types for which there are mouse-handlers de- 
fined. 



(flavorrmethod rdelete-string tvrsheet) string &optional (start 0) (end nil) Method 

Deletes specific strings. It is one of the things to use when dealing with character 
styles that map to variable-width fonts. 

If string is a string, excise a region exactly as wide as that string, or a substring 
specified by start and end, and closes the gap. 



dw:describe-presentation-type type &optional (stream *standard-output*) plural- 
count Function 

Outputs the description of a presentation type provided by the type's definition 
(define-presentation-type macro). 

type The presentation type to be described. 

stream The output stream; the default is *standard-output*. 

plural-count 

Controls whether the description is pluralized. Three values are 
possible: 

nil Do not pluralize the description. 

t Pluralize the description. 

number Include this number in the pluralization. 

Examples: 

(dw:describe-presentati on-type 'integer) ==>an integer 

(dw:describe-presentati on-type 'integer t t) ==>integers 
(dw:describe-presentati on-type 'integer t 12) ==>twelve integers 
(dw:describe-presentati on-type 'integer t 12.2) ==>12.2 integers 

For an overview of dw:describe-presentation-type and related facilities: See the 
section "Defining Your Own Presentation Types". 
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rdeselect &optional (restore-selected t) Message 

Sent to a selectable window by a user program or by a part of the user interface 
to change the selected activity. It is also sent by the system to notify a window 
when it ceases to be the selected window, either because of a change of activities 
or because of selection of a different window within the same activity. When sent 
by the system as a notification of deselection, restore-selected is always nil. 

This message is received by the system and is also received by user daemons that 
wish to be notified when a window becomes deselected. Note that this message can 
be sent to a window that is not the selected window; in that case it is supposed to 
do nothing. 

If rdeselect is sent to the selected window and restore-selected is not nil, the previ- 
ously selected activity is selected. 



(flavorrmethod : deselected- visibility tvrblinker) Method 

Examines the deselected visibility of the blinker. 

(flavorrmethod : deselected- visibility tvrblinker) symbol Init Option 

Sets the initial deselected visibility. By default, it is ron. 

dwr*display-ellipsis-help* Variable 

Controls the presentation of a help message explaining the meaning of a notation 
such as "Foo ... (7)" to indicate 7 possibilities beginning with "Foo". By default, 
the value is t which means that this help message continues to be presented every 
time such a notation is used until the first time such an item is clicked on, at 
which point the value becomes nil and the message is no longer presented. The 
value may be set to nil before this in order to suppress the message at an earlier 
point (in an init file, for example) or it may be set to ralways in order to keep it 
from ever becoming nil, regardless of whether such an item is clicked on or not. 



sirdisplay-item-list stream type list &optional item-string {order-columnwise t) 

Function 

Displays a list of items on stream in evenly spaced columns, stream must be inter- 
active. If it supports mouse sensitivity, the items displayed are also made mouse 
sensitive and of type type. 

list is a list of items to be displayed. Each item in the list is displayed by sending 
the stream an ritem message with type as the first argument. If the item is not it- 
self a list, the item is the second argument to the ritem message. 

If the item to be displayed is a list, the arguments to the ritem message depend 
on item-string. If item-string is not nil, the second argument to the ritem message 
is the first element of the item. If item-string is nil, the item should be an alist 



Page 1218 



whose car is a string to be displayed and whose cdr is the item itself. In this case, 
the second argument to the :item message is the cdr of the item, the third argu- 
ment is ""a", and the fourth argument is the car of the item. The default for 
item-string is nil. 

If order-columnwise is not nil, the items are ordered down columns. If order- 
columnwise is nil, the items are ordered across rows. The default is t. 



sysrdisplay-notification stream note &optional style window-width 



Function 



Displays a notification on stream, note is the notification, returned by the rreceive- 
notification message to an interactive stream. The display includes the time and 
the text of the message as specified in the arguments to tvmotify. 

style is nil or a keyword determining the style of the display: 

nil Displays the time and the text of the message at the current 

cursor position, with indentation. This is the default. 

rstream Sends a :fresh-line message, then displays the time and the 

text of the message, with indentation, in square brackets, then 
displays a Newline. This style is for merging the notification 
display with other output to the stream. 

rwindow Sends a :fresh-line message, then displays the time and the 

text of the message, with indentation, in square brackets. This 
style is for using the entire window to display the notification. 
It assumes the window has been cleared first. 

:pop-up Displays the time and the text of the message at the current 

cursor position, with indentation, then sends a :fresh-line mes- 
sage. This style is used by the notification delivery process to 
display notifications in a pop-up window. 

window-width is nil or the number of characters available on a line to display the 
notification. If window-width is nil or not supplied, the default is the result of 
sending the stream a : size-in-character s message. This is used only to determine 
how much to indent lines other than the first in the notification. If window-width 
is about 110 or more, lines are indented to the beginning of the text of the mes- 
sage (following the time). If window-width is about 100 or less, lines are indented 
only one character. You can supply a large window-width to increase the indenta- 
tion in a narrow window, or supply a small window-width to decrease the indenta- 
tion in a wide window. 

If style is rstream, rwindow, or rpop-up and if a "window of interest" was supplied 
as the first argument to tvmotify, a message is displayed that informs the user 
that FUNCTION S S selects the window of interest. 

sysrdisplay-notification does not return any interesting values, unless style is 
rpop-up. In that case it returns the X and Y coordinates, in pixels, of the begin- 
ning of the line following the text of the notification. 
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zlrdisplay-notifications Function 

Selects a scroll window that displays all notifications received since cold booting. 
This is the same as SELECT N. 



tv:displayed-item-item mouse-sensitive-item Function 

Given a mouse-sensitive item, returns the associated item. 

tv:displayed-item-type mouse-sensitive-item Function 

Given a mouse-sensitive item, returns the type of the item. 



dw:displayed-presentation-clear-highlighting displayed-presentation window &op- 
tional {highlighting-mode runderline) Function 

Eliminates highlighting of a displayed presentation (see dwrdisplayed- 
presentation-set-highlighting) . 

displayed-presentation 

The highlighted presentation. 

window The window displaying the presentation. 

highlighting-mode 

The mode in which the displayed presentation is highlighted, either 
runderline (the default for dwrdisplayed-presentation-set- 
highlighting) or rinverse-video. 

For an overview of dwrdisplayed-presentation-clear-highlighting and related fa- 
cilities, see the section "Controlling Location and Other Aspects of Output". 



dwrdisplayed-presentation-highlighting-boxes displayed-presentation Function 

Returns the value of the highlighting-boxes instance variable of the instance dis- 
played-presentation. 



dw:displayed-presentation-set-highlighting displayed-presentation window &option- 
al (highlighting-mode runderline) Function 

Highlights a displayed presentation. 
displayed-presentation The presentation to highlight. 

window The window displaying the 

presentation. 

highlighting-mode Either runderline (the default) or 

rinverse-video. 
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For an overview of dw:displayed-presentation-set-highlighting and related facili- 
ties, see the section "Controlling Location and Other Aspects of Output". Example: 

(defun presentation-highlighting-test () 
(f resh-1 ine) 

(let ((presentations ())) 
(formatting-item-1 ist 
(t :dont-snapshot-variables (presentations)) 
(loop for i from 1 to 5 do 
(formatting-cel 1 
(t :dont-snapshot-variables (presentations)) 
(let ((presentation 

(dw:with-output-as-presentation (:object i :type 'integer) 
(format t "~R" i)))) 
(when presentation 
(push presentation presentations)))))) 
(let ((n 3) 

(highlighted nil)) 
(loop 
(when highlighted 
(dw:displayed-presentation-clear-highl ighting 
hi ghl i ghted xstandard-outputx 
: inverse-video)) 
(setq highlighted 

(find n presentations :key #'dw:presentation-object)) 
(when highlighted 
(dw : di spl ayed-presentati on-set-hi ghl i ghti ng 
hi ghl i ghted xstandard-outputx 
: inverse-video)) 
(sleep 1) 
(setq n (1+ (random 5))))))) 



dw:displayed-presentation-single-box displayed-presentation Function 

Returns the value of the single-box instance variable of the instance displayed- 
presentation. 

:do-not-echo &rest characters Option 

The characters in characters are interpreted as activation characters and are not 
echoed. The comparison is done with char=, not char-equal, so that the control 
and meta bits are not masked off. The characters are not inserted into the input 
buffer and are not interpreted as input editor commands. When one of these char- 
acters is typed, the final :tyi value returned is the character, not a blip. 

This option exists only for compatibility with earlier releases. New programs 
should use the ractivation option. 
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dw: do-redisplay redisplay -piece &optional (stream *standard-output*) &key full- 
set-cursorpos truncate-p once-only save-cursor-position Function 

Causes incremental redisplay from a redisplay object (created by dwrredisplayer). 
It runs the code in the body of the redisplayer, doing output to stream with respect 
to the display cache points described under dwrwith-redisplayable-output. 

redisplay -piece The redisplay object. 

stream The output stream; the default is *standard-output*. 

:full-set-cursorpos Boolearoptiorepecifyingivhetheithecursoiwilhiove 

backwards or sideways, rather than in strict tty style, so that a spe- 
cial stream is necessary; the default is nil. 

:truncate-p Optionspecifyingwhethertodotheredisplaywiththe 

output stream in truncate mode. With : truncate-p nil, the default, 
the output window rescrolls to update separate parts of the display. 
With : truncate-p t, some updating happens off-screen. 

A third value permitted for this option is :if-necessary. In this 
case, dw: do-redisplay simulates, if necessary, some cursor motion 
on behalf of the output stream. 

:once-only Specifies when t that the redisplay will not be repeat- 

ed. (This is mostly for internal use by table-formatting facilities.) 
The default is nil. 

: save-cursor-position Specifies when t that the cursor should be left at its 
current position rather than moved to the end of the new display. 
The default is nil. 

dw: do-redisplay is one of a number of facilities used to do incremental redisplay. 
For examples, see the file sys:EXAMPLES;Incremental-redisplay.lisp. 

For an overview of dw: do-redisplay and related facilities: See the section "Display- 
ing Output: Replay, Redisplay, and Formatting". 



tv:dolist-noting-progress (var listform name &optional (progress-note-variable 
'tv:*current-progress-note*) (process 'sys:current-process)) &body body Function 

Binds local environment such that the progress of a dolist special form is noted by 
a progress bar displayed in the status line at the bottom of the screen. 

var A variable bound to each successive element in listform on each 

successive iteration. 

listform The list. 

name A string naming the operation being noted. This string is displayed 
with the progress bar. 
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progress-note-variable The variable bound to the note object; the default is 
tv: *current-progress-note* . 

process The process on whose behalf the progress is noted; the default is 
sysrcurrent-process. This is used to determine the precedence of 
notes. 

Example: 

(defun note-element-printing (list) 

(tv:dol ist-noting-progress (element list "Printing elements") 
(print element) 
(sleep 1))) 

For an overview of tvrdolist-noting-progress and related facilities, see the section 
"Progress Indicator Facilities". 



tv:dont-select-with-mouse-mixin Flavor 

Provides a :name-for-selection message that returns nil, so that the user interface 
does not treat the window as a candidate for selection. 



tvrdotimes-noting-progress (var countform name &optional {progress-note-variable 
'tvr*current-progress-note*) (process 'sysrcurrent-process)) &body body Function 

Binds local environment such that the progress of a dotimes special form is noted 
by a progress bar displayed in the status line at the bottom of the screen. 

var A variable bound to the count (0, 1, 2, and so on) on each succes- 

sive iteration. 

countform The number of iterations. 

name A string naming the operation being noted. This string is dis- 
played with the progress bar. 

progress-note-variable The variable bound to the note object; 

the default is tv:*current-progress-note*. 

process The process on whose behalf the progress is noted; this is used 
to determine the precedence of notes. 

Example: 

(defun note-square-roots (n) 
( tv : dot imes-noting-pr ogress 

(count n "Calculating square roots") 
(sqrt count))) 

For an overview of tvrdotimes-noting-progress and related facilities, see the sec- 
tion "Progress Indicator Facilities". 
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:draw-l-bit-raster width height raster from-x frora-y to-x to-y &optional (ones-alu 
:draw) (zeros-alu .-erase) Generic Function 

Draws a pattern onto the screen. The pattern is replicated as needed, as with 
bitblt. Unlike bitblt, which copies bits regardless of any difference in bit depth 
(element type) between the source array and the screen array, :draw-l-bit-raster 
draws one screen pixel for each source pixel (the source must be a 1-bit array). 
Bits that are on in the source are drawn using ones-alu and bits that are off are 
drawn using zeros-alu. For a 1-bit screen, the result is like bitblt would have done 
with tv:alu-seta. 

To say it another way, :draw-l-bit-raster copies pixels from a 1-bit-per-pixel source 
to the destination, which can be any pixel depth. If the destination is also 1-bit- 
per-pixel, :draw-l-bit-raster is identical to bitblt, but if the destination has more 
bits, :draw-l-bit-raster will do the "right" thing where bitblt would produce use- 
less results. For detailed information on all the arguments of :draw-l-bit-raster: 

See the function bitblt. 

For a color screen, ones-alu and zeros-alu can be color alus. So, for instance, ones 
bits might be put out in green and zeros bits in red. Even when drawing in black 
in white to a color screen, :draw-l-bit-raster should be used for drawing stipples, 
because a whole pixel needs to be drawn black for the on pixels, not just one bit 
(which is only part of a pixel). Using :draw-l-bit-raster rather than bitblt is im- 
portant in programs that run without modification on color screens. 



tv:dynamic-item-list-mixin Flavor 

A noninstantiable mixin flavor, built on tv:abstract-dynamic-item-list-mixin used 
as a building block to make instantiable versions listed later. This flavor provides 
a specific means of getting the latest item list, by evaluating a Lisp form, and pro- 
vides the :item-list-pointer instance variable. 

In the operation of this flavor, the old result of evaluating the value of :item-list- 
pointer is saved; if the new result of evaluating the value of :item-list-pointer is 
not the same (compared with the zhequal function), the item list is considered 
changed and the menu is updated. :item-list-pointer is evaluated when the rchoose 
message is sent. 



tv: dynamic-momentary-menu Flavor 

A momentary menu with the tv:dynamic-item-list-mixin and the tvrabstract- 
dynamic-item-list-mixin. 



tv: dynamic-momentary- window-hacking-menu Flavor 

A momentary menu with both the tv:dynamic-item-list-mixin and the tvrwindow- 
hacking-mixin. 
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tv: dynamic-multicolumn-mixin Flavor 

A noninstantiable mixin flavor. It makes a menu have multiple "dynamic" columns. 
Each column comes from a separate item list that is recomputed at appropriate 
times. The instance variable tv:column-spec-list is a list of columns. Each column 
list is in the form: 

(heading item-list-form . options) 

Heading is a string to go at the top of the column, and options are menu item op- 
tions for it (typically a character style specification), item-list-form is a form to be 
evaluated (without side-effects) to get the item list for that column. 



tv:dynamic-pop-up-abort-on-deexpose-command-menu Flavor 

A command menu with the tv:dynamic-pop-up-command-menu and tv:abort-on- 
deexpose mixins. 



tv:dynamic-pop-up-command-menu Flavor 

Specifies a command menu with the temporary-menu and dynamic item-list mixins. 
It is mixed in to form the hardcopy menu flavor press:hardcopy-dynamic-pop-up- 
command-menu-with-highlighting. 



tv:dynamic-pop-up-menu Flavor 

A pop-up menu with the dynamic item-list mixin. 

dw: dynamic- window Resource 

A resource of Dynamic Windows. The resource is created via tvrdefwindow- 
resource with the rinitial-copies option set to 1 and the :reuseable-when option 
set to rdeactivated. (For more information on resources generally, see the section 
"Resources".) 

The following keyword options are available when allocating from or using the Dy- 
namic Window resource: 

:momentary-p Boolean option specifying whether the window provided 

is momentary, that is, whether it is deactivated if the mouse cursor 
is moved off the window. The default is nil. 

:temporary-p Boolean option specifying whether the window provided 

is temporary, that is, whether it locks the superior window until it 
is deactivated. The default is the value of the :momentary-p option. 

rhysteresis If the :momentary-p option is t, specifies the distance, 

in pixels, that the mouse cursor must be from the edge of the win- 
dow before it is deactivated. The default value is 25. 
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Note that in order to use these keywords, you must also supply an optional posi- 
tional argument for the window's superior. In the following example, the superior 
is tvrmain-screen, which is also the default if no arguments are supplied. 

Example: 

(defun dw-resource () 

(using-resource (my-dw dw: dynamic-window tv: main-screen 

:momentary-p t : hysteresis 15) 
(send my-dw :set-size 500 300) 
(send my-dw : expose))) 



dw: dynamic- window Flavor 

The basic Dynamic Window flavor. It provides output-history recording (of dis- 
played presentations) as well as vertical and horizontal scrolling. Dynamic Win- 
dows are created in the same manner as static windows, with the tvrmake-window 
function. 

dw: dynamic- window is built on several component flavors, from which it inherits 
a large number of init options. These include all init options (about 40) to the ba- 
sic, non-Dynamic Window flavor, tvrwindow. Below we provide references to these 
inherited options, but first discuss four that are specific to Dynamic Windows. 

:end-of-page-mode Specifies what happens when queued output exceeds 
the space available in the current viewport of the window. There 
are four possibilities: 

rdefault Uses the global default for Dynamic Windows set by 
the Set Screen Options command or the dwrset-default- 
end-of-page-mode function on which the command is 
based. 

rscroll Causes the window to scroll automatically to accommo- 
date the output. The amount by which the window is 
scrolled is set by the : scroll-factor init option to Dy- 
namic Windows. 

rtruncate Causes scrolling to be the responsibility of the user, 
who must press the SCROLL key to see more output. 

:wrap Causes new output to appear at the top of the window, 
rather than at the bottom as in the case of rscroll or 
rtruncate. 

r scroll-factor Specifies the amount by which a Dynamic Window is 

scrolled when the value of its rend-of-page-mode init option is 
rscroll. Possible values include an integer (number of lines), ratio 
(fraction of the screen), or nil (use the global default set by the Set 
Screen Options command or the function dwrset-default-end-of- 
page-mode). 
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rmouse-blinker-character Specifies the shape of the mouse cursor 

when it is over the window, for example, #\mouse:fat-circle. The 
default is #\mouse:nw-arrow. For a full listing of all the possibili- 
ties, see the section "Mouse-Blinker Characters". 

rmargin-components Specifies a list of the form ( (component-1 [_keys~\ ) 
(component-2 [_keys~\ ) ... (component-n [_keys~\ ) ) , where component-x 
is one of a set of margin-component flavors and keys are zero or 
more keywords or keyword-value pairs appropriate for the given fla- 
vor. Note that the same margin-component flavor can appear more 
than once in this list. For example, you can have more than one 
scroll bar. 

Available margin-component flavors include the following: 

dwrmargin-borders Provides a four-sided, black (normal 

video) border of a specified thickness. 

dw:margin-white-borders Provides a four-sided, white border of a 
specified thickness. 

dwrmargin-whitespace Provides whitespace of a specified thick- 
ness on a specified margin. 

dw:margin-drop-shadow-borders Provides a three-pixel-wide 

black border shadowed on its right and bottom margins by 
an eight-pixel-wide gray border. 

dwrmargin-ragged-borders Provides a ragged (wavy) 

border of a specified thickness. 

dw:margin-label Provides a label on the upper or lower 

margin. By default, the label string is created from the 
name of the window flavor. 

dw:margin-scroll-bar Provides the standard elevator scroll bar 

on the specified margin. 

For more detailed information on these flavors, including allowable 
keywords, see the respective dictionary entry for each. 

The following example illustrates the use of margin-component fla- 
vors. Note that the margin is built from the outside in. 
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bottom : thickness 7) 

bottom) 

left :thickness 10) 



(defun dynamic-window-margin-example () 

(let ((test (tv: make-window 'dw:dynamic-window 
:edges-from : mouse 
: margin-components 
' ((dw:margin-borders :thickness 1) 

(dw:margin-white-borders :thickness 3) 

(dw:margin-borders :thickness 10) 

(dw:margin-white-borders :thickness 8) 

(dw:margin-borders :thickness 3) 

(dw:margin-whitespace :margin :left :thickness 10) 

(dw:margin-scrol 1-bar) 

(dw:margin-whitespace :margin 

(dw:margin-scrol 1-bar :margin 

(dw:margin-whitespace :margin 

(dw:margin-label :margin :bottom 

: style (: sans-serif : italic : normal)) 

(dw:margin-whitespace :margin :top :thickness 10) 

(dw:margin-whitespace :margin :right :thickness 13)) 
:expose-p t))) 
(send test :set-label "Margin Test Window"))) 

The remaining init options to dw: dynamic- window are those it shares with 
tvrwindow. These are documented elsewhere. Below is a list of references and the 
associated init options. 

See the section "Creating a Window". 

:blinker-p 

:default-character-style 

:save-bits 

: superior 

:activate-p 

:expose-p 

See the section "Window Attributes for Character Output". 

:more-p 

:vsp 

:reverse-video-p 

rdeexposed-typeout-action 

rdeexposed-typein-action 

:right-mar gin-character-flag 

:backspace-not-overprinting-flag 

:cr-not-newline-flag 

:tab-nchars 

See the section "Initializing Window Size and Position". 



:left :inside-width 
:x rinside-height 
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:top :inside-size 

:y redges 

rposition :character-width 

rright rcharacter-height 

rbottom :integral-p 

: width :edges-from 

rheight rminimum-height 

:size :minimum-width 

See the section "Window Borders". 

Window borders are comparable to margin components. The two are incompatible: 
you cannot specify one of these flavors if you specify rmargin-components. 

rborders 
:border-mar gin-width 

See the section "Window Labels". 

Window labels are also comparable to margin components. The two are incompati- 
ble: you cannot specify one of these flavors if you specify rmargin-components. 

:name 
rlabel 

See the section "Flavors for Panes and Frames". 

:io-buffer 

In addition to the large overlap in init options between static and Dynamic Win- 
dows, virtually all of the window methods, messages, and functions documented for 
static windows can also be used with Dynamic Windows. These are too numerous 
to list individually as we did for the init options; refer to the following sections for 
more information: 



See the section 

See the section 

See the section 

See the section 

See the section 

See the section 
Graphic Output 

See the section 

See the section 

See the section 

See the section 



'Window Graying". 

'Window Status". 

'Activities and Window Selection". 

'Creating a Window". 

'Character Output to Windows". 

'Graphic Output to Windows" (also see the section "Creating 

). 

'Notifications and Progress Indicators". 
'Using TV Fonts". 
'Handling the Mouse". 
'Window Sizes and Positions". 
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See the section "Window Labels" (Only the :name method). 

Finally, a number of methods intended exclusively for Dynamic Windows are avail- 
able. These are included among both Basic Program Output Facilities and window 
substrate facilities (see the section "Controlling Location and Other Aspects of 
Output" and see the section "Window Substrate Facilities"). 



cprecho-command command-name arguments Function 

Echoes a Command Processor command and its arguments to *standard-output*. 
(The echoed command is presented "acceptably", that is, in such a manner that is 
can subsequently be parsed by accept.) The echoed command is displayed in ital- 
ics, so this is not generally useful. Instead, use the present function with type 
'cp:command. 

command-name The command name (symbol). 

arguments A list of command arguments. 

For an overview of cprecho-command and related facilities: See the section "Man- 
aging Your Program Frame". 



dw:echo-presentation-blip stream blip &optional (start-bp (send stream rread- 

location)) for-context-type Function 

Echoes a presentation blip from the input buffer. 

stream The input stream. 

blip The presentation blip. 

start-bp The position in the input buffer where the presentation blip begins. 

for-context-type The input context on whose behalf the presentation 

blip is echoed. This affects the printing of the blip. For example, 
the Command Processor uses this option to ensure that echoed com- 
mand names are preceded by colons when in the 'command-or-form 
context. 

For an overview of dw:echo-presentation-blip and related facilities: See the sec- 
tion "Presentation Input Blip Facilities". 



(flavorrmethod redges tvrmenu) (left-edge top-edge right-edge bottom-edge) 

Init Option 

Sets various position and size parameters. All the edge parameters are set relative 
to the outside of the superior window. 



(flavorrmethod redges tvrsheet) (left-edge top-edge right-edge bottom-edge) 

Init Option 
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Specifies the x-coordinates of the left and right edges and the y-coordinates of the 
top and bottom edges of the window. 



(flavorrmethod redges tvrsheet) Method 

Returns four values: the left, top, right, and bottom edges, in pixels, relative to 
the superior window, respectively. 



(flavorrmethod :edges-from tvrmenu) source Init Option 

Specifies that the window gets its edge information from the source. If the source 
is a string, the inside of the window is made large enough to display the string in 
the default character style. If the source is a list: {left-edge top-edge right-edge bot- 
tom-edge) it is the same as the redges option. If the source is rmouse , the user is 
asked to point to where the left-top and right-bottom corners should go. If the 
source is a window, the window's edges are copied. 



(flavorrmethod redges-from tvressential-window) source Init Option 

Specifies that the window is to take its edges (position and size) from source, 
which can be one of: 

a string The inside-size of the window is made large enough to display the 

string, in the default character style. 

a list {left-edge top-edge right-edge bottom-edge) Those edges, relative to the 

superior, are used, exactly as if you had used the redges init option. 

rmouse The user is asked to point the mouse to where the top-left and bot- 

tom-right corners of the window should go. (This is what happens when you 
use the [Create] command in the System menu, for example.) 

a window That window's edges are copied. 



reditor-command &rest command-alist Option 

Lets you specify your own input editor editing commands. Each element of com- 
mand-alist is a cons whose car is a character and whose cdr is a symbol or a list. 
If the cdr is a symbol, it is a function to be called with no arguments when the 
user types the associated character. If the cdr is a list, the car of the list is a 
function to be applied to the cdr of the list when the user types the associated 
character. The function can examine the internal special variables that describe 
the state of the input editor. 

If reditor-command specifies a command that is invoked by the same character as 
one of the standard input editor editing commands, the command specified by 
reditor-command overrides the standard command. 
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encode-universal-time seconds minutes hours date month year &optional timezone 

Function 

Given a time in decoded time format, returns the corresponding universal time 
(plus or minus seconds since midnight, January 1, 1900 GMT). 

seconds An integer between and 59. 

minutes An integer between and 59. 

hours An integer between and 23. 

date An integer between 1 and 31. 

month An integer between 1 and 12. 

year An integer indicating the year A.D. This can be shortened to 

an integer in the range 0-99, in which case the year is as- 
sumed equal to the integer modulo 100 and within 50 years of 
the current year; for example, in 1986, 36 is assumed to be 
1936 and 35 to be 2035. 

timezone Hours west (postive) or east (negative) of GMT; it defaults to 

the timezone set for the site (for more information: See the 
section "Specifying a Time Zone for Your Site".) Any real num- 
ber is allowed, but only numbers of the form n or n.5 can cor- 
respond to actual timezones. 

Examples: 

(encode-universal-time 00 00 5 1 9 1986 5) => 2734941600 

(encode-universal-time 00 00 5 1 9 86 5) => 2734941600 



time:encode-universal-time seconds minutes hours day month year &optional time- 
zone Function 

Converts the decoded time into Universal Time format and returns the Universal 
Time as an integer. If you do not specify timezone, it defaults to the current time 
zone adjusted for daylight saving time; if you provide it explicitly, it is not adjust- 
ed for daylight saving time, year can be absolute or relative to 1900 (that is, 84 
and 1984 both work). 



dwrerase-displayed-presentation displayed-presentation window &optional recursive 
as-single-box (clear-inferiors t) Function 

Erases the specified displayed-presentation from window and removes it from the 
output history. Unless recursive is t, this causes a rdelete-displayed-presentation 
message to be sent to window. If displayed-presentation has no inferiors or if as- 
single-box is t, the whole presentation is erased as a region. If clear-inferiors is t 
or if as-single-box is true, the inferiors of the presentation are erased as well. 
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*error-output* Variable 

The value is a stream to which error messages should be sent. Normally, this is 
the same as *standard-output*, but *standard-output* might be bound to a file 
and *error-output* left going to the terminal or a separate file of error messages. 

(with-open-stream (outstream "myfile" :di recti on :output) 
(let ((xstandard-outputx outstream) 

(xerror-outputx outstream)) ;redirects xerror-outputx to myfile. lisp 
(fun-1 ikely-to-signal-an-error)) ;capture any error messages in file 

;end of let restores xerror-outputx, etc. 
;more forms 
) ;end of with-open-f ile closes file 



zlrerror-output Variable 

In your new programs, we recommend that you use the variable *error-output* 
which is the Common Lisp equivalent of zherror-output. See *error-output*. 



cprexecute-command command-name &rest command-arguments Function 

Invokes a Command Processor command from within a program. See also cprbuild- 
command, which cprexecute-command makes use of. 

command-name Symbol or string naming the command to invoke; if a 

string, it must be in the command table to which cp:*command- 
table* is currently bound. 

command-arguments Positional and keyword arguments to the named com- 
mand. 

Examples: 

(cp: execute-command "show file" "test-data. text") 

(cp: execute-command 'si :com-load-system "unifier" 

: condition : always : automatic-answer t) 

For an overview of cprexecute-command and related facilities, see the section 
"Managing the Command Processor". 



(flavorrmethod rexecute tvrmenu) item Method 

Extracts the value from a chosen item and returns it, or performs a side-effect, or 
both. It decides what to return based on the item's type. See the section "Types of 
Menu Items". 

In a program that uses command menus, the :any-tyi message can return a blip 
containing the menu and an item. The program sends the rexecute message to the 
menu to execute the item. See the section "Command Menus". 



Page 1233 



rexecute is sent by the system for other kinds of menus. For example, the rchoose 
message, which returns a value and not an item, uses the rexecute message to re- 
trieve the value from the chosen menu item. 



(flavorrmethod rexpose tvrmenu) Method 

Causes a menu to be exposed, that is, displayed on the screen. 

(flavorrmethod rexpose-p tvressential-window) t-or-nil Init Option 

If non-nil, the window is exposed after it is created. The default is to leave it de- 
exposed. If the value of the option is not t, it is used as the first argument to the 
rexpose message (the turn-on-blinkers option). Note that ractivate-p and rexpose-p 
are arguments in init-options which cannot be specified in the flavor's rdefault- 
init-plist. 

(flavorrmethod rexpose-p tvrmenu) t-or-nil Init Option 

When set to t, the window is immediately exposed. Otherwise, it must be explicitly 
exposed with an rexpose message. 

(flavorrmethod rextra-width tvrchoose-variable-values) arg Init Option 

When rwidth is not specified, specifies the amount of extra space to leave after 
the current value of each variable of the kind that displays its current value 
(rather than a menu of all possible values). This extra space allows for changing 
the value to something bigger. The extra space is specified as either a number of 
characters or a character string. The default is ten characters. If rwidth is speci- 
fied, then rextra-width is ignored. 

(flavorrmethod rfill-p tvrmenu) t-or-nil Init Option 

Specifies whether to use filled format or columnar format. 

(flavorrmethod rfill-p tvrmenu) Method 

Get the menu's fill mode, t is returned from rfill-p if the menu displays in filled 
form rather than columnar form. This message is a special case of the 
rgeometryrset-geometry messages. 



filling-output f&optional stream &key .-fill-column (-.fill-characters '(#\Space)J :after- 
line-break :after-line-break-initially-too :dont-snapshot-variables) &body body Function 

Binds local environment such that character output is filled; that is, filling-output 
makes sure that any output done within its body does not split "words" across 
lines. 
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"Words" are separated by spaces. When a line is broken to keep from wrapping 
past the end of a line, the line break is made at a space. 

stream The output stream; the default is *standard-output*. 

:fill-column Specifiesthelengthoffilledlines.rfill-columnisthe 

cursorpos of the right end of the line. It can be specified in one of 
the following ways: 

integer If the output stream is one whose device units are smaller 
than single characters (pixels, for example) then if the in- 
teger is less than ten, it is interpreted as a number of 
character spaces; otherwise, if the number is greater than 
ten, it is interpreted as a number of device units. Note 
that the requirement that this number be an integer pre- 
cludes the specification of spacing as a fraction of a char- 
acter size: use the list method below to get fractional 
character spacing. (Ten is the number of pixels in a de- 
vice character.) 

string The spacing is the width of the string. 

function The spacing is the amount of space the function would 
consume when called on the stream. 

list The list is of the form (number unit), where unit is one of 

rpixel or rcharacter. '(3 rcharacter) is different from (* 3 
(send stream char-width)) or just 3, in that the charac- 
ter width of whatever stream is really used to do the for- 
matting is correctly used. '(4 rpixel) is different from just 
4 in that it is not subject to the special interpretation of 
small numbers (< 10) normally applied. 

If rfill-column is unspecified, line length is determined as follows: 
If the underlying stream supports the rvisible-cursorpos-limits 
message, as do all Dynamic Windows, the right-hand cursorpos limit 
is used. Otherwise, if the underlying stream supports the rinside- 
size message, the inside size is used. If neither of the two preced- 
ing messages are supported, simple character counting is used, and 
lines are filled to 95 characters in width. 

rfill-characters Specifies a character or characters at which to break 

lines. 

(progn (terpri) 

(filling-output (t : f il 1-column '(30. :character) 
: fill-characters '(#\-)) 
(format t 

" thi s-i s-a-test-of-the-emergency-broadcast-system" ) ) ) 
this-is-a-test-of-the- 
emergency-broadcast-system 
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: after-line-break Specifies a string to be sent to stream after line 

breaks; the string appears at the beginning of each new line. 

: after-line-break-initially- too Boolearoptiorspecifyingvhetheithe 

: after-line-break text is to be written to stream before doing body, 
that is, at the beginning of the first line; the default is nil. 

:fill-on-spaces Obsolete. Use :fill-characters instead. 

Example: 

(defun filling-test () 
(f resh-1 ine) 

(f il 1 ing-output (xstandard-outputx 
: fill-column 420 
:after-l ine-break "Repeat: " 
:after-l ine-break-initial ly-too t) 
(loop for i from 1 to 100 
do 
(format t "Testing ~D " i)))) 

For an overview of filling-output and related facilities, see the section "Controlling 
Line Output". 



cp:find-command-table name &key (if-does-not-exist rerror) Function 

Returns the Command Processor command-table object specified by the command- 
table name. 

name The name (symbol or string) of the command table. 

:if-does-not-exist Specifies what happens if the named command table is 

not found. Three values are possible: 

nil The function returns nil. 

rerror An error is signalled; this is the default. 

rcreate A new command table named name is created and re- 
turned. 

If name is already a command table object, it is returned. So this function is safe 
to use whenever you have a command table arglist. 

For an overview of cprfind-command-table and related facilities: See the section 
"Managing the Command Processor". 



dw:find-graph-node redisplay-helper-stream id &key {key #'identity) {test #'eql) 

Function 
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Searches for a node object given its symbol and the output stream on which it is 
to be displayed. The function returns the object if it finds it, nil otherwise. 

Node objects are created with formatting-graph-node. See the function 
formatting-graph-node. Also, see that facility for an example. 

redisplay-helper-stream The output stream for the node. This should be the 
same stream in use by formatting-graph. 

id A unique identifier for the node. See the function formatting- 

graph-node. 

:key Specifiesafunctionappliedtoanodeobjectbeforecomparisonwith 

id. The default is the identity function. 

:test Specifies the function used to compare node objects with the one 

specified by id. The default is eql. 

For an overview of dw:find-graph-node and related facilities, see the section "Pre- 
senting Formatted Output". 



dwrfind-program-window program-name &rest make-window-options &key (create-p 
t) (activate-p t) (selected-ok t) reuse-test console superior program-state-variables &al- 
low-other-keys Function 

Returns the window (frame) of a program (created via dwrdefine-program- 
framework). If no such window is found and :create-p is nil, then returns nil. 

program-name The name of the program. 

:create-p Specifies whether to create an instance of the program. 
Possible values are 

t, the default: create an instance if one does not exist. 
nil: do not create an instance if one does not exist. 
rforce: create an instance whether or not one exists. 

:activate-p Specifies whether to activate an instance of the pro- 
gram window, if it is created. 

:selected-ok Boolean option specifying whether to return the pro- 
gram window if it is the currently selected activity; the 
default is t. 

:reuse-test Specifies a function to return a non-nil value if an ex- 
isting program window of program-name can be reused. 
The function takes two arguments, the window found and 
the program name. Typically, a window would be reusable 
if deexposed or deactivated. 
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rconsole Specifies the console on which the program window is to 
be sought, dwrfind-program-window returns either a pre- 
viously selected window of the type program-name, or, if 
there is none such and :selected-ok is t, the currently se- 
lected window of type program-name. 

rsuperior Specifies whether to make superior be the superior of the 
program window, if it is created. 

:program-state-variables Specifies a list of initializations for the 
program's state variables. The list is of the form {{<var- 
1> <val-l>) (<var-2> <val-2>) ... (<var-n> <val-n>)). 

If an instance of the program is created, its state vari- 
ables are initialized according to this specification. If an 
instance already exists, its state variables are reset ac- 
cording to the specification. 

Other keywords permitted are programmer-defined and system init options for the 
frame. If an instance of the program is created, it is initialized according to the 
keyword specifications. 

For an overview of dwrfind-program-window and related facilities, see the section 
"Defining Your Own Program Framework". 



dw:find-and-select-program-window name &rest options Function 

Returns the window (frame) of a program (created via dwrdefine-program- 
framework) and selects that window. See the function dwrfind-program-window. 



(flavorrmethod rfinish-typeout sirinteractive-stream) &optional spacing erase? 

Method 

Completes typeout to the window and causes the input buffer to be refreshed. In 
the case of rtemporary typeout, the erase? parameter is used to indicate whether 
or not the typeout overwrote part of the current input by wrapping around the 
screen. It is the responsibility of the program doing the typeout to keep track of 
how much is output. 

spacing can be one of the following keywords: 

Keyword Action 

rnone No spacing before typeout. 

:fresh-line Typeout begins at the beginning of a line. 

:blank-line A blank line precedes typeout. 

If spacing is not specified, a default that depends on the type argument to the 
rstart-typeout method is computed. 
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tv:flashy-scrolling-mixin Flavor 

Provides slow scrolling by moving the mouse through margin regions. 



(flavorrmethod rflashy-scrolling-region tv:flashy-scrolling-mixin) scrolling-region 

Init Option 

Specifies the area in which the mouse maintains its "flashy-scrolling" shape. 

scrolling-region is a list of two lists. The first list specifies the scrolling region for 
the top of the window, and the second for the bottom of the window. 

Each list contains three numbers. The first number is the height, in pixels, of the 
scrolling region. The other two numbers are percentages of the window width 
specifying the width of the scrolling region. The defaults are 50, 0.40, and 0.60. 



(flavorrmethod :follow-p tvrblinker) t-or-nil Init Option 

Sets whether the blinker follows the cursor; if this option is non-nil, it does. By 
default, this is nil, and so the blinker's position gets set explicitly. 



zhfont-baseline font Function 

The baseline of this font; a nonnegative integer. 

zhfont-blinker-height font Function 

The blinker height of the font. 

zhfont-blinker-width font Function 

The blinker width of the font. 

zl:font-char-height font Function 

The character height of the font; a nonnegative integer. 

zl:font-char-width font Function 

The character width of the characters of the font; a nonnegative integer. If the 
zl:font-char-width-table of this font is non-nil, then this element is ignored except 
that it is used to compute the distance between horizontal tab stops; it would typi- 
cally be the width of a space. 

zl:font-char-width-table font Function 
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If nil all the characters of the font have the same width, and that width is given 
by the zl:font-char-width of the font. Otherwise, this is an array of nonnegative 
integers, one for each logical character of the font, giving the character width for 
that character. 



zhfont-chars-exist-table font Function 

nil if all characters exist in the font, or an sysrart-boolean array with one ele- 
ment for each logical character of the file. The element is t if the character exists 
and nil if the character does not exist. 



zhfont-indexing-table font Function 

If nil, all characters are font-raster-width wide. Otherwise, this is the font index- 
ing table of the font, an array with one element for each logical character plus 
one more at the end (to show where the last character stops) containing re- 
positions in the font raster. 

zl:font-left-kern-table font Function 

If nil, all characters of the font have zero left kern. Otherwise, this is an array of 
integers, one for each logical character of the font, giving the left kern for that 
character. 

zl:font-name font Function 

The name of the font. This is a symbol whose binding is this font, and which 
serves to name the font. The print-name of this symbol appears in the printed rep- 
resentation of the font. 

zhfont-raster-height font Function 

The raster height of the font; a positive integer. 

zhfont-raster-width font Function 

The raster width of the font; a positive integer. 

(flavorrmethod rforce-rescan sirinteractive-stream) Method 

Can be sent by a read function that uses the input editor to force a rescan of the 
current input. Before this message is sent, usually some global state has changed 
and the contents of the input buffer are interpreted differently. 

format-cell object printer &key (stream *standard-output*J align-x align-y Function 
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Controls the printing of a table element within a formatting-table or formatting- 
item-list macro (see formatting-table for an example). 

object The table element. 

printer The function used to display each element. The function is passed 
two arguments, the object and the output stream. You can have the 
function write to the stream any information you want included in 
the table for that element. Typical functions to use are princ, 
prinl, and write-string. 

rstream Specifies the output stream; the default is *standard-output*. 

:align-x Specifies how elements of a column should be aligned. The default 
:left, causes the elements to be flush-left in the column. The other 
possible values are rright (flush-right) and reenter (centered). 

:align-y Specifies how elements of a column should be aligned. The default 
rbottom, causes the bottoms of the elements to be aligned at the 
bottom of the cell. The other possible values are :top, and reenter. 

For an example of the use of format-cell: See the function formatting-table. 



format-graph-from-root root-object object-printer inferior-producer &key (stream 
*standard-output*) (dont-draw -duplicates nil) (key #'identity) (test #'eql) (root-is- 
sequence nil) (direction rafter) (default-drawing-mode rline) (default-drawing-options 
nil) (cutoff-depth nil) (border '(rshape rrectangle}) (orientation dwr*default-graph- 
orientation*) (balance-evenly dwr*default-graph-balance-evenly*) (row-spacing 
dwr*default-graph-row-spacing*) (within-row -spacing dwr*default-graph-within- 
row-spacing*) (column-spacing dwr*default-graph-column-spacing*) (within- 
column-spacing dwr*default-graph-within-column-spacing*) (branch-point 
dwr*default-graph-branch-point*) (allow-overlap 
dwr*default-graph-allow-overlap*) Function 

Constructs and displays a tree graph. 

root-object 

The root element of the set, from which the tree can be derived. 

object-printer A function used to display each tree node. The function 

is passed the object associated with that node and the stream on 
which to do output. 

inferior-producer A function that knows how to extract the inferiors 

from a node object. It is passed one argument, the node in question. 

rstream Specifies the output stream; the default is *standard-output*. 

rdont-draw-duplicatesBoolearDptiorepecifyingivhetheiitemathalaredupli- 

cated in the tree are drawn only once (with all the reference lines 
drawn to the same object) or multiple times (once for each occur- 
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rence in the tree); the default is nil. (See the :test and :key op- 
tions.) 

:key Specifiesthefunctionusedtoextractthenodeobjectattributeused 

for duplicate comparison. The default is identity, that is, the object 
itself. 

:test Specifiesthetestfunctionusedforduplicatedetection.Thedefault 

is eql. 

:root-is-sequence Specifiesthatthevaluesuppliedforroctf-o&jectisase- 

quence. Each element of the sequence becomes a separate root. 
(The resulting graphs might not themselves be separate if the 
:dont-draw-duplicates option is t.) 

: direction 

Specifies whether new nodes should be drawn above, below, left, or 
right of the current node. Possible values are rafter and rbefore; 
the default is rafter. 

For : orientation : horizontal, rafter means to the right, rbefore to 
the left. For : orientation : vertical, rafter means below, rbefore 
means above. 

rdefault-drawing-mode Specifiesthedrawingnodeuse&ccon- 

nect nodes of the tree. The default is rline, which connects the 
nodes with solid lines. Other modes are rdashed-line, rarrow, 
rdashed-arrow, rreverse-arrow, and rreverse-dashed-arrow. 

rdefault-drawing-options Specifies one or more drawing function 

options that may override the default options. These are keyword 
options such as rthickness, rgray-level, and the like. The drawing 
options affect the drawing of the borders as well as the drawing of 
the connection lines. 

See the section "Drawing Function Options". 

rcutoff-depth Specifieshowmanylevelsofeachbranchofthetree 

should be explored. The default is nil, which specifies no cutoff. 

rborder Specifies the shape and thickness, in pixels, of the border drawn 

around each node. The default is (: shape : rectangle : thickness 1). 
Other possible shapes are rcircle, roval, and rdiamond. nil means 
no border. 

Abbreviations: 

Full Form Abbreviated Form 

: border (: shape xxxx) : border xxxx 

:border (:thickness n) :border n 
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rorientation Specifiesrverticalorrhorizontalorientationforthe 

"parent node to child node" direction of the graph display. The de- 
fault dwr*default-graph-orientation* is initially set to rvertical. 

rbalance-evenly Specifies whether the subtrees of the tree should all be 

the same size (width or height, depending on rorientation), the size 
of the largest subtree. The default, dwr*default-graph-balance- 
evenly*, is initially set to nil. 

:row-spacing Fonverticabrientation,specifiesthespacing,inpix- 

els, between rows of tree nodes; the default, dwr*default-graph- 
row-spacing*, is initially set to 40. 

:within-row-spacing For rvertical orientation, specifies the spacing, in pix- 
els, between columns of tree nodes; the default, dw:*default-graph- 
within-row-spacing*, is initially set to 20. 

rcolumn-spacing Forrhorizontalorientation,specifiesthespacing,in 

pixels, between columns of tree nodes; the default, dw:*default- 
graph-column-spacing* is initially set to 30. 

rwithin-column-spacing FoahorizontaMentatioispecifiebhe 

spacing, in pixels, between rows of tree nodes; the default, 
dw:*default-graph-within-column-spacing*, is initially set to 10. 

:branch-point Specifies whether the lines connecting nodes should 

branch at the parent node (if set to :at-parent) or whether they 
should make a bend somewhere in the space between generations of 
nodes (if set to rbetween-generations). The default, dw:*default- 
graph-branch-point*, is initially set to rbetween-generations. 
Branching between generations sometimes gives less overlap when 
not all links are to first generation children or when not all nodes 
are the same size. 

Example: 

(defun branch-point-test (&optional 

(branch-point :between-gene rat ions)) 
(f resh-1 ine) 

(format-graph-f rom-root '((a bbbbbbbb) (ccc) (d e f)) 

tf'prinl 
#' (lambda 

(node) (and (consp node) node)) 
:orientation :horizontal 
:branch-point branch-point)) 

rallow-overlap Specifies whether or not subtrees of different superior 

nodes can overlap. dw:*default-graph-allow-overlap*, the default 
that is intitally t, allows overlap. Use rallow-overlap nil when you 
do not need to minimize the amount of space consumed by the 
graph. 
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To see the effect of this keyword, evaluate the following form, then 
evaluate the second form with rallow-overlap set to t and then nil. 

(defun component-flavors (flavor-name) 

(let* ((fl (flavor : find-flavor flavor-name))) 
(remove flavor-name 
(cond 

( (f 1 avor : : f 1 avor-components-composed f 1 ) 

(f 1 avor : f 1 avor-al 1 -components f 1 ) ) 
(t (flavor: :compose-flavor-components 
flavor-name)))))) 
(f ormat-graph-f rom-root ' tv : mi ni mum-wi ndow 

#' (lambda (thing stream) 

(present thing 'flavor : flavor 
: stream stream)) 
tf'cl-user: : component-flavors 
: row-spacing 10 
:within-row-spacing 10 
:al low-overlap t) 

By scrolling horizontally, you will see that in the first case the sub- 
tree for tvressential-window overlaps with subtrees of tvressential- 
activate. 

Examples: 

(defun f ormat-graph-f rom-root-example-1 () 
(f resh-1 ine) 

;; you wouldn't actually bother to write this let, but it makes 
;; for a clearer example, 
(let ((root (pkg-f ind-package "hardcopy")) 
(print-function tf'princ) 
(inferior-producer ft' si :pkg-used-by-l ist)) 
(format-graph-f rom-root root 

print-function 
inferior-producer))) 

;;; Try executing the following Show Flavor Tree command first 

;;; first on simple flavors like net:object and tv:minimum-window. 

;;; More complex flavors let you exercise the horizontal scrolling 

;;; capability of Dynamic Windows. 

(defun flavor-components (flavor-name) 
(f 1 avor : : f 1 avor-1 ocal -components 
(flavor: find- flavor flavor-name))) 

(defun present-flavor (flavor-name 

&optional (stream xstandard-outputx)) 
(present flavor-name 'flavor : flavor-name : stream stream)) 
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(cp:def ine-command (com-show-flavor-tree : command-table "Global") 
((root-flavor-name 'flavor: flavor-name)) 
(f resh-1 ine) 
(f ormat-graph-f rom-root root-f 1 avor-name 

#' present-f 1 avor #' f 1 avor-components 
:dont-draw-dupl icates t :orientation :horizontal )) 

For an overview of format-graph-from-root and related facilities, see the section 
"Presenting Formatted Output". 



format-item-list list &key (stream *standard-output*) printer presentation-type (key 
^'identity) (fresh-line t) (return-at-end t) (order-columnwise t) (optimal-number-of- 
rows si:*optimal-number-of-rows*) (additional-indentation 2) (equalize-column- 
widths nil) max-width max-height Function 

Displays the elements of a list in a tabular format. 

list The list of items to display. 

rstream Specifies the output stream; the default is *standard-output*. 

rprinter Specifiesthefunctionusedtodisplaytheitems;thedefaultprinter 

is princ. The function is passed two arguments, an item and the 
output stream. 

This option and the :presentation-type option are mutually exclu- 
sive. 

:presentation-type Specifies the presentation type used to display the 

items. Items are output via calls to present as this type. Items out- 
put as presentations can be used as mouse-sensitive input in the 
proper input context. 

This option and the rprinter option are mutually exclusive. 

:key A function of one argument that will extract from an element the 

part to be printed in place of the whole element. Example: 

(format-item-list sys:al 1 -processes :key #'si :process-priority) 

:fresh-line Booleanoptionspecifyingvhetherrfresh-lineopera- 

tion should be performed on the output stream before the table is 
displayed; the default is t. 

:return-at-end Booleanoptionspecifyingvhetheranewlineshouldbe 

printed on the output stream when the table display is completed; 
the default is t. 

rorder-columnwise Booleanoptionspecifyingwhethertableitemsareor- 
dered as a series of columns, the default, or rows. 
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Column-wise ordering: Row-wise ordering: 

14 7 12 3 

2 5 8 4 5 6 

3 6 9 7 8 9 

:optimal-number-of-rows Specifiesthenumberofrowsintheta- 

ble. If the number of rows specified is too small or too large to ac- 
commodate the list of items supplied, the appropriate number of 
rows closest to that specified is used. 

: additional-indentation Specifiesthenumberofcharactersby 

which the left margin of the table is indented; the default is 2. 

requalize-column-widths BoolearDptiorepecifyingvhetheiall 

columns have the same width (that of the widest column); the de- 
fault is nil. 

:max-width Specifiesthemaximum width, inpixels, of the table 

display. 

:max-height Specifiesthemaximumheight,inpixels,ofthetable 

display. 

For an overview of format-item-list and related facilities, see the section "Format- 
ting Tables". 

dw:format-output-macro-continuation f&key :name (:warn-p t) :dont-snapshot- 
variables) var-list &body body Function 

Performs variable snapshotting. Use this macro in place of zhnamed-lambda in 
defining macros that require snapshotting. 

(def macro my-formatting-macro ((&optional (stream 'xstandard-outputx) 

&key dont-snapshot-variables) 
&body body) 
(dw : f ormat-output-macro-def aul t-stream stream) 
1 (my- formatting-macro-hel per- function 
, stream 

(dw: format-output-macro-continuation (:name my-formatting-macro 

: dont-snapshot-vari abl es 
dont-snapshot-vari abl es) 
(, stream) 
. ,body))) 

(defun my-formatting-macro-helper-function (continuation xstream) 
(funcall continuation xstream)) 
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dw:format-output-macro-default-stream var Function 

Defaults t or nil to *standard-output*; for use by output macros. Example: 

(def macro my-formatting-macro ((&optional (stream 'xstandard-outputx)) 

&body body) 
(dw : f ormat-output-macro-def aul t-stream stream) 
1 (my- formatting-macro-hel per- function 
, stream 
(dw: named-continuation my-formatting-macro (, stream) . , body))) 

(defun my-formatting-macro-helper-function (continuation xstream) 
(funcall continuation xstream)) 



format-sequence-as-table-rows sequence printer &rest options &key (stream 
*standard-output*) &allow-other-keys Function 

Displays the elements in a sequence as a series of table rows. 

sequence The sequence to be displayed. Each element of the sequence be- 
comes one row in the resulting table. 

printer The function used to display each element. The function is passed 
two arguments, an element of the sequence and an output stream. 
You can have the function write to the stream any information you 
want included in the table row for that item within appropriate 
formatting-cell forms. 

options These are the same options as those of formatting-table, which see. 



Note that each element becomes a row of cells, not a single cell. Use formatting- 
item-list if you want a single cell. 

rstream Specifies the output stream; the default is *standard-output*. 

(defun format-sequence-as-table-rows-test () 
(f resh-1 ine) 

(f ormat-sequence-as-tabl e-rows 
sys:al 1 -processes 
#' (lambda (process stream) 

(formatting-cell (stream) 

(present process 'si:process :stream 
stream)) 
(format-cell (si :process-whostate process) 
tf'princ 
: stream stream)))) 

Additional keyword options available for this function are the same as those 
to formatting-table. 
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For an overview of format-sequence-as-table-rows and related facilities, see the 
section "Formatting Tables". 



format-textual-list sequence function &key (separator ",") finally if-two filled after- 
line-break conjunction (stream *standard-output*) Function 

Outputs a sequence of items as a textual list; for example, "1 2 3 4" becomes "1, 2, 
3, and 4": 

(defun simple-list-formatter () 
(f resh-1 ine) 
(format-textual -1 ist '(1 2 3 4) #'princ : conjunction "and")) 

sequence The sequence to output. 

function The function used to print sequence elements. This should be a 
function of two arguments: the object to print and the stream to 
send it to. 

rseparator Specifiesthecharacterstousetoseparateelementsof 

a textual list. The default is ", " (comma followed by a space). 

rfinally Specifiestheseparatortobeusedbetweenthenext-to-lastandlast 

elements of the list. The default is nil, meaning use the regular 
separator (specified by the rseparator option). A typical value is " 

and ". 

:if-two Specifiestheseparatortousewhenthereareonlytwoelementsin 
the list. A typical value is " and ". 

rfilled Specifies whether the list should be "filled"; the default is nil. 

A filled list is one containing Newline characters at appropriate 
points to prevent wrapping of output from right margin to left. 
Thus, specifying : filled t for a long list results in two or more 
separate lines of output — each of a length less than the width of 
the output window — rather than one long, wrapped line. Line 
breaks come between list elements, not within. 

Another value permitted for this option is rbefore. This is like t, 
except that in the case where a line break occurs at a rseparator, 
the break is made before the separator rather than after. 

: after-line-break In : f i 1 1 ed tmode,specifiesthestringtoinsertatthe 

beginning of each new line. This is useful for specifying leading in- 
dentation, etc. (See the rfilled option.) 

rconjunction Specifiesastringtouseinthepositionbetweenthe 

last two elements. Typical values are "and" and "or". 

This option is similar to the rfinally option, but does not affect the 
separator between the last two elements, unless only two elements 
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occur. That is, the rconjunction option takes care of the two- 
element case; the :if-two option is not necessary if you use this op- 
tion. 

rstream Specifies the output stream; the default is *standard-output*. 

For an overview of format-textual-list and related facilities, see the section "For- 
matting Textual Lists". Example: 

(format-textual -1 ist sys:area-l ist #'prin1 : filled t :after-l ine-break " ") 



formatting-cell f&optional stream &key align-x align-y dont-snapshot-variables) 
&body body Function 

Binds local environment to control the printing of a table element within a 
formatting-table or formatting-item-list macro (see the latter facilities for ex- 
amples). 

stream The output stream; the default is *standard-output*. 

:align-x Specifies how elements of a column should be aligned. The default 
:left, causes the elements to be flush-left in the column. The other 
possible values are rright (flush-right) and reenter (centered). 

:align-y Specifies how elements of a column should be aligned. The default 
rbottom, causes the bottoms of the elements to be aligned at the 
bottom of the cell. The other possible values are :top, and reenter. 

rdont-snapshot-variables Specifies whether the free variables with- 

in the output macro should be snapshotted. The default of this op- 
tion, nil, specifies that the free variables should be snapshotted. See 
the section "Snapshotting Variables". 

For an overview of formatting-cell and related facilities, see the section "Format- 
ting Tables". 



formatting-column (&optional stream &rest options) &body body Function 

Controls column layout within a formatting-table macro (see the latter facility for 
examples). 

stream Specifies the output stream; the default is *standard-output*. 
options rdont-snapshot-variables is the only option available. 

rdont-snapshot-variables Specifies whether the free variables with- 

in the output macro should be snapshotted. The default of this op- 
tion, nil, specifies that the free variables should be snapshotted. See 
the section "Snapshotting Variables". 
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For an overview of formatting-column and related facilities, see the section "For- 
matting Tables". 



formatting-column-headings (&optional stream &rest options) &body forms 

Function 

Controls the display of column headings within a formatting-table macro. If any 
form in forms is just a string, it is treated as 

(formatting-cel 1 (stream) 

(write-string (string) 
stream)) 

Example: 

(defun table-with-column-headings 

(&optional (column-one-label "Number")) 
(f resh-1 ine) 
(formatting-table () 

(formatting-column-headings () 

(formatting-cel 1 () (write-string column-one-label)) 
(formatting-cel 1 () "Square")) 
(loop for i from 1 to 10 
as square = (* i i) 
do 
(formatting-row () 
(formatting-cel 1 () 

(princ i)) 
(formatting-cel 1 () 
(princ square)))))) 

stream Specifies the output stream; the default is *standard-output*. 
options The following option is available: 

:underline-p Booleanoptionspecifyingwhethercol- 

umn headings are underlined; the default is nil. 

Note that it is an error to have more than one formatting-column-headings form 
within a formatting-table form. If you need two rows to display a column heading 
use a form like the following: 

(defun foo () 

(f resh-1 ine) 

(formatting-table () 

(formatting-column-headings () "Parsley" "Sage" "Rose- 
mary" "Thyme"))) 

For an overview of formatting-column-headings and related facilities, see the sec- 
tion "Formatting Tables". 
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formatting-graph f&optional stream &key (orientation dw:*default-graph- 
orientation*) (inverted-center dw:*default-graph-inverted-center*J (balance-evenly 
dw:*default-graph-balance-evenly*J (row-spacing dw:*default-graph-row-spacing*J 
(within-row-spacing dw:*default-graph-within-row-spacing*J (column-spacing 
dw:*default-graph-column-spacing*J (within-column-spacing dw:*default-graph- 
within-column-spacing*) (branch-point dw:*default-graph-branch-point*J (allow- 
overlap dw:*default-graph-allow-overlap*J (default-drawing-mode rlinej default- 
drawing-options dont-snapshot-variables) &body body Function 

Binds the local environment to output a graph connecting node objects generated 
in the body of the macro. The node objects are created by the macro formatting- 
graph-node. 

stream The output stream; the default is *standard-output*. 

rorientation Specifiesrverticalonhorizontalorientationforthe 

"parent node to child node" direction of the graph display. The de- 
fault dw:*default-graph-orientation* is initially set to rvertical. 

rinverted-center Specifies whether the lines connecting nodes are to di- 

verge at the parent node (when set to nil) or at the first child node 
(when set to t). The default, dw:*default-graph-inverted-center* is 
initially set to nil. 

rbalance-evenly Specifies whether the subtrees of the tree should all be 

the same size (width or height, depending on rorientation), the size 
of the largest subtree. The default, dw:*default-graph-balance- 
evenly*, is initially set to nil. 

:row-spacing Fonverticabrientation,specifiesthespacing,inpix- 

els, between rows of tree nodes; the default, dw:*default-graph- 
row-spacing*, is initially set to 40. 

:within-row-spacing For rvertical orientation, specifies the spacing, in pix- 
els, between columns of tree nodes; the default, dw:*default-graph- 
within-row-spacing*, is initially set to 20. 

rcolumn-spacing Fonhorizontalorientation,specifiesthespacing,in 

pixels, between columns of tree nodes; the default, dw:*default- 
graph-column-spacing* is initially set to 30. 

rwithin-column-spacing FoahorizontaMentatioispecifiebhe 

spacing, in pixels, between rows of tree nodes; the default, 
dw:*default-graph-within-column-spacing*, is initially set to 10. 

:branch-point Specifies whether the lines connecting nodes should 

branch at the parent node (if set to :at-parent) or whether they 
should make a bend somewhere in the space between generations of 
nodes (if set to rbetween-generations). The default, dw:*default- 
graph-branch-point*, is initially set to rbetween-generations. 



Page 1251 



Branching between generations sometimes gives less overlap when 
not all links are to first generation children or when not all nodes 
are the same size. 

Example: 

(defun branch-point-test (&optional 

(branch-point :between-gene rat ions)) 
(f resh-1 ine) 

(format-graph-f rom-root '((a bbbbbbbb) (ccc) (d e f)) 

tf'prinl 
W (lambda 

(node) (and (consp node) node)) 
:orientation :horizontal 
:branch-point branch-point)) 

rallow-overlap Specifies whether or not subtrees of different superior 

nodes can overlap. dwr*default-graph-allow-overlap*, the default 
that is intitally t, allows overlap. Use rallow-overlap nil when you 
do not need to minimize the amount of space consumed by the 
graph. 

To see the effect of this keyword, evaluate the following form, then 
evaluate the second form with rallow-overlap set to t and then nil. 

(defun component-flavors (flavor-name) 

(let* ((fl (flavor : find-flavor flavor-name))) 
(remove flavor-name 
(cond 

( (f 1 avor : : f 1 avor-components-composed f 1 ) 

(f 1 avor : f 1 avor-al 1 -components f 1 ) ) 
(t (flavor: :compose-flavor-components 
flavor-name)))))) 
(format-graph-f rom-root ' tv : mi ni mum-wi ndow 

#' (lambda (thing stream) 

(present thing 'flavor : flavor 
: stream stream)) 
tf'cl-user: : component-flavors 
: row-spacing 10 
:within-row-spacing 10 
:al low-overlap t) 

By scrolling horizontally, you will see that in the first case the sub- 
tree for tvressential-window overlaps with subtrees of tvressential- 
activate. 

rdefault-drawing-mode Specifiesthedrawingnodeuse&ccon- 

nect nodes of the tree. The default is rline, which connects the 
nodes with solid lines. Other modes are rdashed-line, rarrow, 
rdashed-arrow, rreverse-arrow, and rreverse-dashed-arrow. 
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rdefault-drawing-options Specifies one or more drawing function 

options that may override the default options. These are keyword 
options such as rthickness, :gray-level, and the like. The drawing 
options affect the drawing of the borders as well as the drawing of 
the connection lines. 

See the section "Drawing Function Options". 

:dont-snapshot-variables Specifies whether the free variables with- 

in the output macro should be snapshotted. The default of this op- 
tion, nil, specifies that the free variables should be snapshotted. See 
the section "Snapshotting Variables". 

Note: you must supply a form to create borders when you use formatting-graph, 
since you do not get them automatically as you would with format-graph-from- 
root. 

Example: 

(defun simple-graph (stream) 
(fresh-line stream) 

(formatting-graph (stream :orientation :horizontal) 
(let ((node-a (formatting-graph-node (stream) 

(surrounding-output-with-border 

(stream : shape : rectangle : thickness 3) 
(princ 'a stream))))) 
(formatting-graph-node (stream :connections l (:right , node-a) 

:drawing-mode :dashed-l ine) 
(surrounding-output-with-border 

(stream : shape : rectangle : thickness 3) 
(princ 'b stream)))))) 

If you want to try this example, compile it first. For a more complex example, see 
the function formatting-graph-node. 

For an overview of formatting-graph and related facilities, see the section "Pre- 
senting Formatted Output". 



formatting-graph-node (&optional stream &key id connections (drawing-mode t)) 
&body body Function 

Binds local environment to create node objects for use by the formatting-graph 
macro. For an example, see the dictionary entry for the latter facility. 

stream The output stream; the default is *standard-output*. 

rid Specifiesaunique identifier forthe node. Anode identifierisused 

as an argument to dw:find-graph-node, see the function dwrfind- 
graph-node. 
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rconnections Specifiestheconnectionsbetweenthisnodeandoneor 

more other nodes. The specification is a list in the form ( (key node- 
object-1) (key node-object-2) ... (key node-object-n)), where key is 
one of :left, rright, rabove, or rbelow; or one of rbefore or rafter. If 
the orientation of the graph is vertical, rbefore is equivalent to 
rabove, if the orientation is horizontal, rbefore is equivalent to 
rleft. Analogously, rafter is equivalent to rbelow (vertical) or rright 
(horizontal). 

rdrawing-mode Specifiesthedrawingmodeusedtoconnectthisnode 

with other nodes of the tree. This specification locally overrides the 
rdefault-drawing-mode specified by formatting-graph. Possible 
modes are rline, rdashed-line, rarrow, rdashed-arrow, rreverse- 
arrow, and rreverse-dashed-arrow. 

r drawing-options Specifies any drawing options that are to override the 

default drawing options. The drawing options are rthickness, rcolor, 
rgray-level, and the like. If r drawing-options is nil, the default 
drawing options are used. See the function formatting-graph. See 
the function format-graph-from-root. See the section "Drawing 
Function Options". 



Example: 
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(defun graph-1 (list unique-id-p) 
(let ((stream xstandard-outputx)) 
(fresh-line stream) 
(formatting-graph (stream) 

(labels ((do-one (contents &rest connections) 
(let ((node nil)) 
(when unique-id-p 
(let ((al ready-there 

(dw: find-graph-node stream contents))) 
(when al ready-there 

(dw : connect-graph-nodes 

stream al ready-there connections) 
(setq node al ready-there)))) 
(unless node 

(setq node (formatting-graph-node 
(stream 

:id contents 

:connections connections) 
(surrounding-output-with-border 
(stream) 

(prinl contents stream))))) 
(when (consp contents) 

(dolist (sublist contents) 

(do-one sublist :after node)))))) 
(do-one list))))) 

(graph-1 ' (a (b c) c) nil) 

(graph-1 ' (a (b c) c) t) 

(graph-1 '(#1=(x y z) (w #1tf) y) nil) 

(graph-1 '(#1=(x y z) (w #1tf) y) t) 

For an overview of formatting-graph-node and related facilities, see the section 
"Presenting Formatted Output". 



formatting-item-list (&optional stream &key inter-row-spacing inter-column-spacing 
row-wise output-row-wise n-rows n-columns inside-width inside-height max-width 
max-height) &body body Function 

Binds local environment to output a list of items created in the body of the macro 
as a table. 



Example: 
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(defun formatting-1 ist-example () 
(f resh-1 ine) 

(formatting-item-1 ist (t :n-columns 3) 
(loop for (p) in si : active-processes 
do 
(when p 

(formatting-cel 1 () 

(write-string (si : process-name p))))))) 

stream The output stream; the default *standard-output*. 

:inter-row-spacing Specifiesthenumberofpixelsbetweenrows;thede- 
fault is 0. 

rmter-column-spacmgDeterminestheamountofspacebetweencolumnsof 

the table; the default is the width of two spaces, rinter-column- 
spacing can be specified in one of the following ways: 

integer If the output stream is one whose device units are smaller 
than single characters (pixels, for example) then if the in- 
teger is less than ten, it is interpreted as a number of 
character spaces; otherwise, if the number is greater than 
ten, it is interpreted as a number of device units. Note 
that the requirement that this number be an integer pre- 
cludes the specification of spacing as a fraction of a char- 
acter size: use the list method below to get fractional 
character spacing. (Ten is the number of pixels in a de- 
vice character.) 

string The spacing is the width of the string. 

function The spacing is the amount of space the function would 
consume when called on the stream. 

list The list is of the form (number unit), where unit is one of 

rpixel or rcharacter. '(3 rcharacter) is different from (* 3 
(send stream char-width)) or just 3, in that the charac- 
ter width of whatever stream is really used to do the for- 
matting is correctly used. '(4 rpixel) is different from just 
4 in that it is not subject to the special interpretation of 
small numbers (< 10) normally applied. 



:row-wise 



Boolean option specifying that the table is built by rows, that is, 
that the each succeeding item in the list be placed in the same row, 
one column after the previous item (except for line breaks); the de- 
fault is t. nil specifies that each item be placed in the same col- 
umn, one row below the previous item. 
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:output-row-wise Booleanoptionspecifyingthatthetablebedisplayed 

row-by-row. The default is nil, causing the table to be displayed in 
the order in which it is constructed (See the :row-wise option.) If 
you specify :row-wise nil :output-row-wise t, the graph will be 
drawn faster, but the row cells will not be in the given order. For 
example, compare the results of running the following with the list 
'(abcdefghijkl), setting :row-wise to t and then nil. 

(defun what-order (1 row-wise) 
(terpri) 

(stack-let ((things (make-array 100 : f il 1-pointer 0))) 
(formatting-item-1 ist 

(t : row-wise row-wise : output-row-wise t) 
(dolist (x 1) 

(formatting-cel 1 () 

(vector-push-extend x things) 
(princ x)))) 
(coerce things 'list))) 

:n-rows Specifies the number of rows the table should have. 

:n-columns Specifies the number of columns the table should have. 

:inside-width Specifies the exact width, in pixels, of the table dis- 

play. 

rinside-height Specifiestheexactheight,inpixels,ofthetabledis- 

play. 

:max-width Specifiesthemaximum width, inpixels, of the table 

display. 

:max-height Specifiesthemaximumheight,inpixels,ofthetable 

display. 

For an overview of formatting-item-list and related facilities, see the section "For- 
matting Tables". 



formatting-multiple-columns (&optional stream &key number-of-columns) &body 
body Function 

Binds the local environment such that the lines of text generated by the body of 
the macro are output in a multiple-column format. 

stream The output stream; the default is *standard-output*. 

:number-of-columns Specifiesthenumberofcolumnsintowhichtheitems 

are arranged. If this is unspecified, it uses as many columns as will 
fit, based on the stream's :inside-size. 
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Example: 

(defun test-columns (&optional (stream xstandard-outputx)) 
(loop for hundreds from to 100 by 100 do 
(terpri stream) 

(formatting-multi pie-columns (stream) 
(loop for j from 1 to 20 do 

(format stream "~d ~r~%" (+ j hundreds) (+ j hundreds)))))) 

Usage note: You should not use formatting-table within formatting-multiple- 
columns. Instead, use the rmultiple-columns option to formatting-table, see the 
function formatting-table. Also, formatting-table works with redisplay, while 
formatting-multiple-columns does not redisplay. 

For an overview of formatting-multiple-columns and related facilities, see the sec- 
tion "Formatting Tables". 



formatting-row (&optional stream &rest options) &body body Function 

Controls row layout within a formatting-table macro (see the latter facility for 
examples). 

stream The output stream; the default is *standard-output*. 
options There is only one option: 

:dont-snapshot-variables Specifies whether the free 

variables within the output macro should be snap- 
shotted. The default of this option, nil, specifies that 
the free variables should be snapshotted. See the sec- 
tion "Snapshotting Variables". 

For an overview of formatting-row and related facilities, see the section "Format- 
ting Tables". 



formatting-table (&optional stream &key equalize-column-widths extend-width ex- 
tend-height inter-row-spacing inter-column-spacing multiple-columns (multiple- 
column-inter-column-spacing dw::inter-column-spacing) (equalize-multiple-column- 
widths nil) (output-multiple-columns-row-wise nil)) &body body Function 

Binds local environment to output items in a tabular format. 

This macro must be used in conjunction with at least two others. The first, 
formatting-row or formatting-column, controls whether items are output as table 
rows or table columns, respectively. The second, formatting-cell or format-cell, 
controls the printing of each item. Contrast the output of the following two exam- 
ples: 
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(defun row-oriented-table-formatting () 
(f resh-1 ine) 
(formatting-table () 

(loop for i from 1 to 10 

as square = (x i i) 
do 
(formatting-row () 
(formatting-cel 1 () 

(princ i)) 
(formatting-cel 1 () 
(princ square)))))) 

(defun column-oriented-table-formatting () 
(f resh-1 ine) 
(formatting-table () 

(loop for i from 1 to 10 

as square = (* i i) 
do 
(formatting-column () 
(format-cell i tf'princ) 
(format-cell square tf'princ))))) 

stream The output stream; the default is *standard-output*. 

requalize-column-widths BoolearDptiorepecifyingvhetheiall 

columns have the same width (that of the widest column); the de- 
fault is nil. 

:extend-width Specifieswhetherthespacingoftablecolumnsisex- 

tended; the default is nil. Alternative values are t, meaning make 
use of the full horizontal space available, or a number, indicating 
the number of pixels over which to extend the table. If the table is 
already wider than the requested total, then this option makes no 
difference. 

rextend-height Specifieswhetherthespacingoftablerowsisextend- 

ed; the default is nil. Alternative values are t, meaning make use of 
the full vertical space available, or a number, indicating the number 
of pixels over which to extend the table. If the table is already 
taller than the requested total, then this option makes no differ- 
ence. 

:inter-row-spacing Specifiestheminimumnumberofpixelsinsertedbe- 

tween rows of the table; the default is 0. This value will be the ac- 
tual number of pixels inserted unless overridden by the rextend- 
height option. 

rinter-column-spacing Determines the amount of space inserted between 
columns of the table; the default is the width of a space character. 



Page 1259 



This value can be overriden by the :extend-width option, rinter- 
column-spacing can be specified in one of the following ways: 

integer If the output stream is one whose device units are smaller 
than single characters (pixels, for example) then if the in- 
teger is less than ten, it is interpreted as a number of 
character spaces; otherwise, if the number is greater than 
ten, it is interpreted as a number of device units. Note 
that the requirement that this number be an integer pre- 
cludes the specification of spacing as a fraction of a char- 
acter size: use the list method below to get fractional 
character spacing. (Ten is the number of pixels in a de- 
vice character.) 

string The spacing is the width of the string. 

function The spacing is the amount of space the function would 
consume when called on the stream. 

list The list is of the form (number unit), where unit is one of 

rpixel or rcharacter. '(3 rcharacter) is different from (* 3 
(send stream char-width)) or just 3, in that the charac- 
ter width of whatever stream is really used to do the for- 
matting is correctly used. '(4 rpixel) is different from just 
4 in that it is not subject to the special interpretation of 
small numbers (< 10) normally applied. 



rmultiple-columns BoolearoptiorEpecifyingchattablerowsbalistributed 
among a series of two or more columns. 

For example, 

(defun multiple-column-example (multiple-columns) 
(f resh-1 ine) 
(formatting-table 

(t :mul tiple-columns multiple-columns) 
(loop for i from 1 to 4 

as point = (+ 50 (* i i)) 
do 
(formatting-row () 
(formatting-cel 1 () 

(format t "Set Point #~D: ~D 
i point)))))) 



Set Point #1 


51 


Set Point #2 


54 


Set Point #3 


59 


Set Point #4 


66 


becomes 
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Set Point #1 : 


51 


Set Point #3: 


59 


Set Point #2: 


54 


Set Point #4: 


66 



The arrangement of rows and columns generated is such that the 
number of columns is maximized, the number of rows is minimized, 
and the hole, if any, left in the lower right corner of the table is 
the smallest possible. 

:multiple-column-inter-column-spacing Specifiefeheumbeuf 

pixels to insert between columns in a multiple-column display 
(rmultiple-columns option is t). It defaults to the value of the 
rinter-column-spacing option. 

requalize-multiple-column-widths BoolearDptiorepecifyingvhetheiall 

columns in a multiple column display (rmultiple-columns option is 
t) have the same width (that of the widest column); the default is 
nil. 

:output-multiple-columns-row-wise Boolean option specifying whether 

columns in a multiple-column display (rmultiple-columns option is 
t) are displayed by outputting all the elements in one row followed 
by all in the next, and so on. The default is nil, meaning that the 
order of display is "column-wise": first all the elements in one col- 
umn are output, then all the elements in the next, and so on. 

The resulting display is the same no matter which way this flag is 
set; only the order in which the elements are displayed is changed. 
This affects the order in which calls to formatting-row are made 
within the body of the table-formatting macro. In the default case, 
calls are made in the order given; in the alternative case, call order 
is unpredictable. See the section "Snapshotting Variables". 

For an overview of formatting-table and related facilities, see the section "For- 
matting Tables". 



formatting-textual-list (&optional stream &key (separator ",") finally if-two filled 
after-line-break conjunction) &body body Function 

Binds local environment to output a sequence of items as a textual list. This 
macro must be used in conjunction with the formatting-textual-list-element macro 
specifying the printing function. 

Example: 
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(defun simple-list-formatting () 
(f resh-1 ine) 

(formatting-textual-1 ist (t : conjunction "and") 
(loop for i from 1 to 4 
do 
(formatting-textual-1 ist-element () 
(princ i))))) 

stream The output stream; the default is *standard-output*. 

rseparator Specifiesthecharacterstousetoseparateelementsof 

a textual list. The default is ", " (comma followed by a space). 

rfinally Specifiestheseparatortobeusedbetweenthenext-to-lastandlast 

elements of the list. The default is nil, meaning use the regular 
separator (specified by the rseparator option). A typical value is " 

and ". 

:if-two Specifiestheseparatortousewhenthereareonlytwoelementsin 
the list. A typical value is " and ". 

rfilled Specifies whether the list should be "filled"; the default is nil. 

A filled list is one containing Newline characters at appropriate 
points to prevent wrapping of output from right margin to left. 
Thus, specifying : filled t for a long list results in two or more 
separate lines of output — each of a length less than the width of 
the output window — rather than one long, wrapped line. Line 
breaks come between list elements, not within. 

Another value permitted for this option is rbefore. This is like t, 
except that in the case where a line break occurs at a rseparator, 
the break is made before the separator rather than after. 

: after-line-break In : f i 1 1 ed tmode,specifiesthestringtoinsertatthe 

beginning of each new line. This is useful for specifying leading in- 
dentation, etc. (See the rfilled option.) 

rconjunction Specifiesastringtouseinthepositionbetweenthe 

last two elements. Typical values are "and" and "or". 

This option is similar to the rfinally option, but does not affect the 
separator between the last two elements, unless only two elements 
occur. That is, the rconjunction option takes care of the two- 
element case; the rif-two option is not necessary if you use this op- 
tion. 



For an overview of formatting-textual-list and related facilities, see the section 
"Formatting Textual Lists". 
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formatting-textual-list-element (&optional stream) &body body Function 

Controls the printing of items output as textual list elements within a formatting- 
textual-list macro. 

Example: 

(formatting-textual-1 ist (t : conjunction "and") 
(loop for i from 1 to 4 doing 

(formatting-textual-1 ist-element () (princ i)))) 

stream The output stream; the default is *standard-output*. 

For an overview of formatting-textual-list-element and related facilities, see the 
section "Formatting Text". 



fquery Flavor 

fquery is a simple condition built on condition. It is signalled by the fquery func- 
tion when its : signal-condition option is t. The messages examine the arguments 
given to the fquery function. 

Message Value returned 

roptions Returns the first argument to the fquery function. 

rformat-string Returns the second argument to the fquery function (its for- 

mat control string or prompt). 

:format-args Returns the rest of the arguments to the fquery function (the 

arguments to its format control string). 

The rchoice proceed type is provided. It has one argument, which is a value to be 
returned from the call to the fquery function. 



fquery options &optional fquery-format-string &rest fquery-format-args Function 

Asks a question, printed by (format query-io format-string format-args...), and re- 
turns the answer, fquery takes care of checking for valid answers, reprinting the 
question when the user clears the screen, giving help, and so forth. 

options is a list of alternating keywords and values, used to select among a variety 
of features. Most callers have a constant list that they pass as options (rather than 
consing up a list whose contents varies). The keywords allowed are: 

:type 

What type of answer is expected. The currently defined types are :tyi (a single 
character), rreadline (a line terminated by a carriage return), and :mini- 
buffer-or-readline. :tyi is the default. 

:mini-buffer-or-readline is like the rreadline value. The exception is 
that if fquery is called from inside Zwei or Zmail, the line of text is 
read from the minibuffer instead of from the zl:query-io stream. The 
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idea of this feature is to let you write things that work equally well in- 
side Zwei or on their own; if you use this value, you make it easier for 
your code to be integrated into a Zwei extension. 

rchoices Defines the allowed answers. The allowed forms of choices are complicat- 
ed and explained below. The default is the same set of choices as the 
zl:y-or-n-p function. Note that the :type and rchoices options should be 
consistent with each other. 

rlist-choices If t, the allowed choices are listed (in parentheses) after the ques- 
tion. The default is t; supplying nil causes the choices not to be listed 
unless the user tries to give an answer that is not one of the allowed 
choices. 

rhelp-function Specifies a function to be called if the user presses the 

HELP key. The default help function simply lists the available choices. 
Specifying nil disables special treatment of HELP. If you specify a help 
function, it should take one argument, the stream on which to display 
the help message. The function can get the list of available choices from 
the value of the special variable formatrfquery-choices. 

: signal-condition Basically a way to intervene and provide an answer to 

a query without asking the user. 

The default for : signal-condition is nil. When its value is t, the fquery 
function signals an fquery condition with proceed type of rchoice before 
prompting the user. Any handler can invoke the rchoice proceed type in 
order to return a value from fquery. When no handler handles the con- 
dition, fquery proceeds normally and queries the user. 

The following example answers "yes" to every "Delete this entry?" query 
occurring inside do- it that has : signal-condition t: 

(condition-bind 

((fquery #' (lambda (condition) 

(and (send condition ' :proceed-type-p ':choice) 
(equal (send condition ': format-string) 

"Delete this entry? ") 
(values ':choice t))))) 
(do-it)) 

:fresh-line If t, zl:query-io is advanced to a fresh line before asking the ques- 
tion. If nil, the question is printed wherever the cursor was left by pre- 
vious typeout. The default is t. 

:beep If t, fquery beeps to attract the user's attention to the question. The de- 
fault is nil, which means not to beep unless the user tries to give an an- 
swer that is not one of the allowed choices. 

:clear-input If t, fquery throws away typeahead before reading the user's re- 
sponse to the question. Use this for unexpected questions. The default is 
nil, which means not to throw away typeahead unless the user tries to 
give an answer that is not one of the allowed choices. In that case, ty- 
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peahead is discarded since the user probably wasn't expecting the ques- 
tion. 

rselect If t and zl:query-io is a visible window, that window is temporarily se- 
lected while the question is being asked. The default is nil. 

:make-complete If t and zl:query-io is a typeout-window, the window is 

"made complete" after the question has been answered. This tells the 
system that the contents of the window are no longer useful. The default 
is t. 

rstream Has as its value the stream to use for both input and output. The de- 
fault value is the value of the global variable zl:query-io. 

:no-input-save If t, tells the input editor not to put the response to 

the question into its history. The default is nil. 

: status This option takes effect only if zl:query-io is a window and :type is :tyi. 
If the value is rselected and the window becomes deselected while 
fquery is waiting for input, fquery returns :status. If the value is 
rexposed and the window becomes deexposed or deselected while fquery 
is waiting for input, fquery returns :status. If the value is nil, fquery 
continues to wait for input when the window is deexposed or deselected. 
The default is nil. 

This option is intended for queries that appear in temporary windows 
that might become deexposed or deselected before the user responds. 

The argument to the rchoices option is a list each of whose elements is a choice 
(with one exception, described in the next paragraph). A choice is a list whose cdr 
is a list of the user inputs that correspond to that choice. These should be charac- 
ters for :type :tyi or strings for :type rreadline. The car of a choice is either a 
symbol that fquery should return if the user answers with that choice, or a list 
whose first element is such a symbol and whose second element is the string to be 
echoed when the user selects the choice. In the former case nothing is echoed. In 
most cases :type rreadline would use the first format, since the user's input has 
already been echoed, and :type :tyi would use the second format, since the input 
has not been echoed and furthermore is a single character, which would not be 
meaningful to see on the display. 

The last element in the list of choices can be the symbol :any (instead of being a 
list, like all other choices). Then if the user gives some response that is not one of 
the other choices, fquery does not complain and reprompt the user, but instead re- 
turns what the user typed (a single character or a string, depending on the :type 
option). 

For example, the zl:yes-or-no-p function uses this list of choices: 

((t "Yes") (nil "No")) 

and the zl:y-or-n-p function uses this list: 

(((t "Yes.") #/Y #/T #\space) 
((nil "No.") #/N #\rubout)) 
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If you want to use the formatted output functions instead of zhformat to produce 
the prompting message, write: 

(f query options (format :outfmt exp-or-string exp-or-string ...)) 

formatroutfmt puts the output into a list of a string, which makes zhformat print 
it exactly as is. There is no need to supply additional arguments to the fquery un- 
less it signals a condition. In that case the arguments might be passed so that the 
condition handler can see them. 



(flavorrmethod :fresh-line tvrsheet) Method 

Gets the cursor position to the beginning of a blank line. Do this in one of two 
ways. If the cursor is already at the beginning of a line (that is, at the inside left 
edge of the window), clear the line to make sure it is blank and leave the cursor 
where it was. Otherwise, advance the cursor to the next line and clear the line 
just as if a #\return had been output. The behavior of this operation is not affect- 
ed by the :cr-not-newline-flag init option. 



:full-rubout token Option 

If the user rubs out all the characters that were typed, control is returned from 
the input editor immediately. Two values are returned: nil and token. If the user 
does not rub out all the characters, the input editor propagates multiple values 
back from the function that it calls, as usual. In the absence of this option, the in- 
put editor simply waits for more characters to be typed and ignores any additional 
rubouts. 



(flavorrmethod rfunction tvrbasic-choose-variable-values) function Init Option 

Specifies the function called when the value of a variable is changed. See the sec- 
tion "The Optional Constraint Function". The default is nil (no function). 



(flavorrmethod rfunction tvrchoose-variable-values) arg Init Option 

Specifies the function to be called if the user changes the value of a variable. The 
default is nil (no function). See the section "The Optional Constraint Function". 



tvr*f unction-keys* Variable 

The value is an alist, each entry of which describes a subcommand of the FUNC- 
TION key. Entries are of the form: 

(char function documentation optionl option2 ...) 

For an explanation of the components of the entries: See the function tvradd- 
function-key. Use tvradd-f unction-key to add a new entry or redefine an existing 
one rather than changing the value of tvr*f unction-keys* yourself. 
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tv:function-text-scroll-window Flavor 

Lets you provide a function to print the items in a text scroll window. 

(flavorrmethod rgeometry tvrmenu) list Init Option 

Sets up the complete menu geometry, using a list to specify the columns, rows, in- 
side-width, inside-height, max-width, and max-height. See the section "The Geome- 
try of a Menu". 

(flavorrmethod rgeometry tvrmenu) Method 

This message returns a list of six elements, which constitute the menu's geometry. 
These are the menu's default constraints, with nil in unspecified positions; con- 
trast this with the rcurrent-geometry message. 

(flavorrmethod rget-pane tvrbasic-constraint-frame) pane-name Method 

Returns the pane (the inferior window itself) that was named by the symbol pane- 
name in the rpanes specification of this frame. 

get-decoded-time Function 

Returns the current time in decoded time format. The nine values returned are: 
second (0-59); minute (0-59); hour (0-23); date (1-31); month (1-12); year (A.D.); day- 
of-week (0 [Monday] -6 [Sunday]); a flag (t or nil) indicating whether daylight sav- 
ings time is in effect; and the timezone (hours west of GMT). 

The following example was run at 10:39:18 on Friday, 9/5/86 EDT: 

(get-decoded-time) => 

18 

39 

10 

5 

9 

1986 

4 

T 

5 



dwrget-program-pane name &key (:if-does-not-exist rerror) Function 

Returns specified pane in a program frame created with dwrdefine-program- 
framework. 

name The name of the pane as specified in the rpanes option to 
dwr def ine-progr am-f r amework. 
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:if-does-not-exist Specifies the action to be taken if the specified frame 

is not found. Possible values are rerror or nil. 

For an overview of dw:get-program-pane and related facilities, see the section 
"Defining Your Own Program Framework". 



time:get-time Function 

Gets the current time, in decoded form. Return seconds, minutes, hours, date, 
month, year, day-of-the-week, and daylight-savings-time-p, with the same meanings 
as time:decode-universal-time. Note that you can also get the current time using 
zl-user:get-decoded-time. 

get-universal-time Function 

Returns the current time, in Universal Time form. 



(flavorrmethod :gray-array-for-inferiors tvrgray-deexposed-inferiors-mixin) gray 

Init Option 

Specifies gray as the graying specification to use in graying areas of this screen or 
frame that contain no windows. See the section "Window Graying Specifications". 



(flavorrmethod :gray-array-for-inferiors tvrgray-deexposed-inferiors-mixin) 

Method 

Returns the graying specification that this frame or window uses in graying areas 
that contain no windows. See the section "Window Graying Specifications". 



(flavorrmethod :gray-array-for-unused-areas tvrgray-unused-areas-mixin) 

Method 

Returns the graying specification that this frame or window uses in graying areas 
that contain no windows. See the section "Window Graying Specifications". 



(flavorrmethod rgray-array-for-unused-areas tvrgray-unused-areas-mixin) gray 

Init Option 

Specifies gray as the graying specification to use in graying areas of this screen or 
frame that contain no windows. See the section "Window Graying Specifications". 



tvr*gray-arrays* Variable 

A list of variables bound to predefined graying specifications. You can use one of 
these as the source of a pattern for background or deexposed window graying. You 
can also make your own graying specifications and add them to this list. See the 
section "Window Graying Specifications". 
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tv:gray-deexposed-inferiors-mixin Flavor 

This flavor, mixed into a screen or a frame, gives it the ability to gray areas with- 
in it that contain windows that are not fully exposed. 



tv:gray-unused-areas-mixin Flavor 

This flavor, mixed into a screen or a frame, gives it the ability to gray areas with- 
in it that contain no windows. 



(flavorrmethod :half-period tvrblinker) n-60ths Init Option 

Sets the initial value of the half-period, that is, the time between xor's of the 
blinker. This defaults to 15. 



(flavorrmethod rhalf-period tvrblinker) Method 

Examines the half-period of the blinker. 

(flavorrmethod redges-from tvressential-window) source Init Option 

Specifies that the window is to take its edges (position and size) from source, 
which can be one of: 

a string The inside-size of the window is made large enough to display the 

string, in the default character style. 

a list {left-edge top-edge right-edge bottom-edge) Those edges, relative to the 

superior, are used, exactly as if you had used the redges init option. 

rmouse The user is asked to point the mouse to where the top-left and bot- 

tom-right corners of the window should go. (This is what happens when you 
use the [Create] command in the System menu, for example.) 

a window That window's edges are copied. 



(flavorrmethod rhandle-asynchronous-character sirinteractive-stream) character 

Method 

Finds the function associated with character in the asynchronous characters list. It 
calls the function with two arguments, character and self. This is mainly for use 
by the Keyboard Process, although user processes can use it also. 



(flavorrmethod rhandle-mouse tvressential-mouse) Method 

The mouse overseer sends this message when the mouse enters the window. The 
method calls the default mouse handler, which returns when the mouse moves out- 
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side the window. You can add an after daemon to turn off the blinker when the 
mouse leaves, for example. 

dw:handler-applies-in-limited-context-p context limiting-context-type Function 

Intended for use in the rtester forms of mouse handlers. It takes a context as pro- 
vided in the rcontext keyword argument to a tester, and a presentation type to use 
as the limiting-context-type. It returns t if and only if the presentation type in the 
context is a subtype of the limiting-context-type. Because of caching, it is much 
faster than using dwrpresentation-subtypep for this purpose, and it provides the 
convenience of extracting the presentation type from the context. See the function 
dwrpresentation-subtypep-cached. 

This function is typically used with translating handlers whose to-presentation-type 
is a subtype of sysrexpression. For example, a translator from a .bin or ibin 
pathname to a . 1 i sp pathname may be intended for use only in the pathname in- 
put context, not when any Lisp object is acceptable. By putting dwrrhandler- 
applies-to-limited-context-p in the rtester of the handler, the handler can be lim- 
ited to contexts that are looking for some type of pathname. 

Example: 

(def ine-presen tat ion- translator source-file-pathname 
(pathname pathname 

: tester ((ignore &key context) 

(dw:handler-appl ies-in-1 imited-context-p 
context 'pathname))) 
(pathname) 
(send (send (send pathname : generic-pathname) :get 
: qf asl -source-f i 1 e-unique-id) 
: new-pathname : version : newest)) 

For an overview of dw:handler-applies-in-limited-context-p and related facilities: 
See the section "Programming the Mouse: Writing Mouse Handlers". 

(flavorrmethod rheight tvribeam-blinker) n-pixels Init Option 

Sets the initial height of the blinker. It defaults to the line-height of the window. 

(flavorrmethod rheight tvrmenu) arg Init Option 

Height in pixels. Includes margins, as opposed to rinside-height, which does not 
include margins. 

(flavorrmethod rheight tvrrectangular-blinker) n-pixels Init Option 

Sets the initial height of the blinker, in pixels. By default, it is set to the height 
of the default character style of the window associated with the blinker. 
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(flavorrmethod rheight tvrsheet) outside-height Init Option 

Specifies the outside height of the window. 

dw:help-program-check-for-help-wakeup blip Function 

Checks whether the presentation type of blip is window-wakeup-help. If so, exe- 
cutes a throw to catch tag return-from-read-command; otherwise, calls 
dw::default-window-wakeup-handler. 

dw:help-program-help help-program stream string-so-far &optional (format-string 
"") &rest format-args Function 

Causes the string, "You are typing a command at the Program-name Program." , to 
be displayed when the user presses the HELP key, and, if used at the top level — 
that is, if supplied as the value of :help in a user::define-program-framework 
form — also displays "For accessing more detailed documentation about the Pro- 
gram-name Program itself, click on the Program-name command.", where in this 
last sentence Program-name is appropriately. 

You can build your own help function using dw:help-program-help as in the fol- 
lowing example, taken from the Graphic Editor. 

(defmethod (graphic-editor-help graphic-editor) (stream string-so-far) 

(dw: help-program-help self stream string-so-far " 
Click on a command from the menus at the right, 
or select a shape to enter from the menu at the bottom. 

")) 

graphic-editor-help is supplied as the value for :help as described above. When 
the user presses the HELP key, the help program displays "You are typing a com- 
mand at the Graphic-editor Program. Click on a command from the menus at the 
right, or select a shape to enter from the menu at the bottom." 

The arguments for dw:help-program-help are: 

help-program The name of the program the help facility is for. 

stream The stream that help-program uses. 

string-so-far A string to be displayed after the initial string mentioned above. 

(flavorrmethod rhighlighted-items tvrmenu-highlighting-mixin) items Init Option 

When a menu with the menu-highlighting mixin is created, the list of items to be 
initially highlighted may be specified. The items in this list must be eq to items in 
the menu's :item-list. The default is nil. 

(flavorrmethod rhighlighted-values tvrmenu-highlighting-mixin) Method 
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Get the list of highlighted items. Refers to the items by value. For instance, if 
your item-list is an association list, with elements (string . symbol), this message 
uses symbol. This only works for menu items that can be executed without side- 
effects, not, for example, the :eval and rfuncall kinds.See the section "tvrmultiple- 
menu-mixin Messages". 



tvrhollow-rectangular-blinker Flavor 

Displays as a hollow rectangle; the editor uses such blinkers to show you which 
character the mouse is pointing at. This flavor includes tvrrectangular-blinker, 
and so all of tvrrectangular-blinker's init options and messages work on this too. 



(flavorrmethod :home-cursor tvrsheet) Method 

Moves the cursor to the upper left corner of the window. 

(flavorrmethod :home-down tvrsheet) Method 

Moves the cursor to the lower left corner of the window. 

(flavorrmethod rhysteresis tvrhysteretic-window-mixin) n-pixels Init Option 

Sets the initial value of the hysteresis, in pixels. It defaults to 25. (decimal). 

(flavorrmethod rhysteresis tvrhysteretic-window-mixin) Method 

Examines the hysteresis of the window, in pixels. 

tvrhysteretic-window-mixin Flavor 

By mixing this flavor into your window, you control the mouse for a small area 
outside the window as well as the area inside the window. You can control the 
hysteresis, which is the number of pixels away from the window that the mouse 
has to get before this window ceases to own it. This mixin is used by momentary 
menus, so that if you accidentally slip a bit outside the menu, the menu will not 
vanish; you have to get well away from it before it vanishes. 

(The dwr dynamic- window resource has a rhysteresis option, allowing you to get 
Dynamic Windows with this capability mixed in.) 

tvribeam-blinker Flavor 

This flavor of blinker displays as an I-beam (like a capital I). Its height is control- 
lable. The lines are two pixels wide, and the two horizontal lines are nine pixels 
wide. 
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indenting-output (stream indentation) &body body 



Function 



Binds local environment to control the insertion of spaces or other characters at 
the beginning of each newline output to a stream. 

stream The output stream. As a special case, t and nil are abbreviations 
for *standard-output*. 



indentation 



What gets inserted at the beginning of each line out- 



put to the stream. Four possibilities exist: 

integer If the output stream is one whose device units are smaller 
than single characters (pixels, for example) then if the in- 
teger is less than ten, it is interpreted as a number of 
character spaces; otherwise, if the number is greater than 
ten, it is interpreted as a number of device units. Note 
that the requirement that this number be an integer pre- 
cludes the specification of spacing as a fraction of a char- 
acter size: use the list method below to get fractional 
character spacing. (Ten is the number of pixels in a de- 
vice character.) 

string The spacing is the width of the string. 

function The spacing is the amount of space the function would 
consume when called on the stream. 

list The list is of the form (number unit), where unit is one of 

rpixel or rcharacter. '(3 rcharacter) is different from (* 3 
(send stream char-width)) or just 3, in that the charac- 
ter width of whatever stream is really used to do the for- 
matting is correctly used. '(4 rpixel) is different from just 
4 in that it is not subject to the special interpretation of 
small numbers (< 10) normally applied. 

The function should be a function to print a string. It receives one argument, the 

output stream. Because the system calls this function with other streams, for ex- 
ample, with a dummy stream to determine the space requirements of the output, it 
should output something of the same size each time it is called. 

You should begin the body with (terpri stream), or equivalent, to position the 
stream to the indentation initially. That is, it is perfectly valid to indent only sub- 
sequent lines. 

Examples: 

(defun simple-indenter () 
(indenting-output (t 10) 
(loop for i from 1 to 5 
do 
(terpri) 
(format t "This is indented line ~d" i)))) 
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The trace special form uses indenting-output as follows: 

(flet ((indent (stream) 

(loop for n from 1 below trace-level do 
(write-char (if ... #\| #\sp) stream)))) 
(indenting-output (xtrace-outputx #' indent) 
(terpri xtrace-outputx) 
...)) 

For an overview of indenting-output and related facilities, see the section "Con- 
trolling Line Output". For a related facility, see the function sysrwith-indentation. 



dwrindependently-redisplayable-format stream format-string &rest format-args 

Function 

Outputs a formatted string such that each format argument is independently re- 
displayable. (See the function dwrwith-redisplayable-output.) 

stream The output stream; the default is *standard-output*. 
format-string The format-control string. (See the function format.) 

format-args The format arguments. 

The format-string is parsed at compile time, resulting in a series of calls to 
dwrredisplayable-format or format. Some restrictions result: 

• stream may not be nil, although format would permit it. 

• format commands that need all the format arguments, like conditionals, itera- 
tions, or gotos, cannot be used. 

dwrindependently-redisplayable-format is one of a number of facilities used to do 
incremental redisplay. For examples, see the file sys:EXAMPLES;INCREMENTAL- 

REDISPLAY.LISP. 

For an overview of dwrindependently-redisplayable-format and related facilities: 
See the section "Displaying Output: Replay, Redisplay, and Formatting". 



rinferior-select sheet Message 

Returns non-nil if it is okay to select sheet, or nil if it is not okay. If the message 
returns nil, presumably some appropriate action such as selecting a different win- 
dow has already been performed. 

This message is sent and received by the system. It is normally sent under two 
circumstances: 

• If a window is selected, and if the window includes a flavor that makes it par- 
ticipate in its superior's activity, the window sends its superior an rinferior- 
select message with itself as the argument. Flavors that make windows partici- 
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pate in their superiors' activities include tv:select-relative-mixin, tv:pane-mixin, 
and tvrbasic-typeout-window. 

• If a window receives a : select-relative message and the window's activity is not 
the currently selected activity, it sends its superior an rinferior-select message 
with itself as the argument. 

The rinferior-select message is propagated upwards through all levels of the win- 
dow hierarchy until it reaches a screen. This informs the direct and indirect supe- 
riors of window that it has been selected (or selected relative to its activity). When 
a frame receives an rinferior-select message, it saves sheet as its selected-pane and 
passes the message on, substituting itself for sheet. 

All currently extant methods return a non-nil value. Only panes look at the re- 
turned value; they don't allow themselves to be selected if the returned value is 
nil. This permits a frame to refuse to allow its selected-pane to be changed. 



(flavorrmethod rinit tvrsheet) init-plist Method 

Sets initial characteristics of the window, processing options in init-plist. This mes- 
sage is sent by the system; you might need to supply a rbefore or rafter daemon 
for it. 



rinitial-input string &optional begin end cursor-position Option 

When the input editor is entered, string is inserted into the input buffer as if the 
user had typed it. The user can edit the string before activating, begin and end 
are indices into string and mark the portion of the string to be copied into the in- 
put buffer, begin defaults to 0; end defaults to (zlrarray-active-length string), cur- 
sor-position is an index into the string where the cursor should initially be placed. 
The default is to place the cursor at the end of the portion of the string copied in- 
to the input buffer, string can be nil, which is the same as not specifying the op- 
tion. 

In the following example, the user is prompted for a line of text. The input buffer 
initially contains the name of the user, and the cursor is placed at the beginning 
of the input buffer. 

(with-input-edi ting-options 

((: initial-input fs: user-personal -name nil nil 0)) 
(prompt-and-read :string "Full name: ")) 

Placing a string in the input buffer is one style of input defaulting. Another style 
leaves the input buffer empty but allows a default to be yanked with c-n-Y. See 
the option rinput-history-default. 



timerinitialize-timebase &optional ut {use-network t) Function 
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Initializes the timebase. If ut, a universal-time integer, is supplied, uses ut as the 
current time. If ut is nil or unspecified and if use-network is not nil, queries local 
network hosts to find out the current time, (use-network is t by default.) If it can- 
not get the time from the network, or if ut and use-network are both nil, prompts 
the user for a string to parse as the current time. On machines in the 3600 fami- 
ly, if the calendar clock has been set, uses the calendar clock reading as the de- 
fault time for the user to specify. If the calendar clock has not been set, offers to 
set it to the time that the user specifies. 

This is called automatically during system initialization. You might want to call it 
yourself to correct the time if it appears to be inaccurate or wrong. See the func- 
tion time:set-local-time. 



(flavorrmethod rinput-editor sirinteractive-stream) read-function &rest read-args 

Method 

Applies read-function to read-args after invoking the input editor. For more infor- 
mation: See the section "The Input Editor Program Interface". 

Normally a program does not send this message itself; it uses the special form 
with-input-editing. See the function with-input-editing. 

Input Editing Options 



ractivation function &rest arguments Option 

For each character typed, the input editor invokes function with the character as 
the first argument and arguments as the remaining arguments. If the function re- 
turns nil, the input editor processes the character as it normally would. Otherwise, 
the cursor is moved to the end of the input buffer, a rescan of the input is forced 
(if one is pending), and the blip (ractivation character numeric-arg) is returned by 
the final sending of the :any-tyi message to the stream. Activation characters are 
not inserted into the input buffer, nor are they echoed by the input editor. It is 
the responsibility of the reading function to do any echoing. For instance, 
zhreadline, not the input editor, types a Newline at the end of the input buffer 
when RETURN, END, or LINE is pressed. 



rblip-handler function Option 

Specifies a function to handle blips received while inside the input editor, function 
must be a function of two arguments. The first argument is the blip; the second 
argument is the stream that received the blip. The handler is invoked when the 
input editor receives a blip. If the handler returns non-nil, no further action is 
taken. If it returns nil and a rpreemptable option is in effect, the actions specified 
by that option are taken. Otherwise, the default blip handler is invoked. 

In the following example, the user is prompted for a line of text. While entering 
this text, the user may also click the left or middle mouse buttons. If the left 
mouse button is clicked, the coordinates of the mouse with respect to the window 
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are inserted into the input buffer. If the middle button is clicked, the name of the 
window is inserted. 

(defun example-blip-handler (blip ignore) 

(destructuring-bind (type click window x y) blip 
(and (eq type : mouse-button) 
(selectq click 
(#\mouse-l-1 
(si : ie-insert-string (format nil " ~D ~D" x y)) 
t) 

(#\mouse-m-1 
(si : ie-insert-string (format nil " ~A" window)) 
t))))) 

(with-input-edi ting-options (( :bl ip-handler 'example-bl ip-handler)) 
(prompt-and-read :string "Blip handler test: ")) 

si:ie-insert-string is an internal function for inserting a string into the input buf- 
fer. Since the language for writing input editor commands has not been formal- 
ized, this example might not work in a later release. 



:brief-help &rest help-option Option 

When the user presses HELP, the input editor displays a message determined by 
help-option on the same line as the typein. The message is displayed in the default 
typeout font, and none of the usual conventions about input editor typeout apply. 
:brief-help overrides :complete-help, :merged-help, and :partial-help. 

help-option can have one element, which can be a string, a function, or a symbol; 
or it can have more than one element. For an explanation: See the section "Dis- 
playing Help Messages in the Input Editor". 

This option is intended for programs like fquery that need to supply only a brief 
help message, usually about expected typein. 



rcommand function &rest arguments Option 

This option is used to implement nonediting single-keystroke commands. For each 
character typed, the input editor invokes function with the character as the first 
argument and arguments as the remaining arguments. If the function returns nil, 
the input editor processes the character as it normally would. Otherwise, control is 
returned from the input editor immediately. Two values are returned: a blip of the 
form (rcommand character numeric-arg) and the keyword rcommand. Any un- 
scanned input typed before the command character remains in the input buffer, 
available to the next read operation from the stream. 



rcomplete-help &rest help-option Option 
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When the user presses HELP, the input editor types out a message determined by 
help-option. None of the standard input editor help is displayed. If a :brief-help op- 
tion has been specified, it overrides :complete-help. :complete-help overrides 
:merged-help and :partial-help. 

help-option can have one element, which can be a string, a function, or a symbol; 
or it can have more than one element. For an explanation: See the section "Dis- 
playing Help Messages in the Input Editor". 

This option is intended for programs that supply their own input editor help mes- 
sages. 



:do-not-echo &rest characters Option 

The characters in characters are interpreted as activation characters and are not 
echoed. The comparison is done with char=, not char-equal, so that the control 
and meta bits are not masked off. The characters are not inserted into the input 
buffer and are not interpreted as input editor commands. When one of these char- 
acters is typed, the final :tyi value returned is the character, not a blip. 

This option exists only for compatibility with earlier releases. New programs 
should use the ractivation option. 



reditor-command &rest command-alist Option 

Lets you specify your own input editor editing commands. Each element of com- 
mand-alist is a cons whose car is a character and whose cdr is a symbol or a list. 
If the cdr is a symbol, it is a function to be called with no arguments when the 
user types the associated character. If the cdr is a list, the car of the list is a 
function to be applied to the cdr of the list when the user types the associated 
character. The function can examine the internal special variables that describe 
the state of the input editor. 

If reditor-command specifies a command that is invoked by the same character as 
one of the standard input editor editing commands, the command specified by 
reditor-command overrides the standard command. 



rfull-rubout token Option 

If the user rubs out all the characters that were typed, control is returned from 
the input editor immediately. Two values are returned: nil and token. If the user 
does not rub out all the characters, the input editor propagates multiple values 
back from the function that it calls, as usual. In the absence of this option, the in- 
put editor simply waits for more characters to be typed and ignores any additional 
rubouts. 



rinitial-input string &optional begin end cursor-position Option 
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When the input editor is entered, string is inserted into the input buffer as if the 
user had typed it. The user can edit the string before activating, begin and end 
are indices into string and mark the portion of the string to be copied into the in- 
put buffer, begin defaults to 0; end defaults to (zharray-active-length string), cur- 
sor-position is an index into the string where the cursor should initially be placed. 
The default is to place the cursor at the end of the portion of the string copied in- 
to the input buffer, string can be nil, which is the same as not specifying the op- 
tion. 

In the following example, the user is prompted for a line of text. The input buffer 
initially contains the name of the user, and the cursor is placed at the beginning 
of the input buffer. 

(with-input-edi ting-options 

((: initial-input fs: user-personal -name nil nil 0)) 
(prompt-and-read :string "Full name: ")) 

Placing a string in the input buffer is one style of input defaulting. Another style 
leaves the input buffer empty but allows a default to be yanked with c-n-Y. See 
the option rinput-history-default. 



rinput-history-default string Option 

Specifies string as the default to be yanked by c-n-Y. string is temporarily placed 
at the head of the input history. If the user types c-n-Y n-Y, the true first ele- 
ment of the input history is yanked. c-n-S c-n-Y shows string at the head of the 
input history, and the entries in the input history are shifted down by one. 

In the following example, the user is prompted for a line of text. The input buffer 
is initially empty, but the c-n-Y command yanks a default, which is the name of 
the user. 

(with-input-edi ting-options 

(( : input-history-default fs: user-personal -name)) 
(prompt-and-read :string "Full name: ")) 

This option is used by the rpathname option for prompt-and-read. 



:input-wait &optional whostate function &rest arguments Option 

When the input editor waits for input, it sends the stream an :input-wait message 
with the arguments to the :input-wait option as arguments. In addition, unless the 
rsuppress-notifications option has been specified, :input-wait returns when a noti- 
fication is received. See the message :input-wait. 



:input-wait-handler function &rest arguments Option 

When the input editor is waiting for input it sends the stream an :input-wait 
message. After :input-wait returns, the input editor applies function to arguments. 
The input editor does not process the input or display the notification until func- 
tion returns. 
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:merged-help function &rest arguments Option 

When the user presses HELP, the input editor types out a message determined by 
the arguments, function is a function that takes at least two arguments. The input 
editor calls the function to print the help message. The first argument is the 
stream. The second argument is a continuation (a list) to print a standard message 
describing how to invoke input editor commands and other information about the 
stream. When the function wants to print this message, it should apply the car of 
the continuation to the cdr. If any arguments are supplied, they are the remaining 
arguments to the function. 

If a :brief-help or :complete-help option has been specified, it overrides rmerged- 
help. :merged-help overrides :partial-help. 

This option is intended for programs that want to decide when and where to dis- 
play their own help messages and the standard help message. 



:no-input-save Option 

The input editor does not save the scanned contents of the input buffer on the in- 
put history when returning from the reading function. This is intended for use by 
functions such as fquery that use the input editor to ask simple questions whose 
responses are not worth saving. zl:yes-or-no-p uses :no-input-save by default. 



rnotification-handler function &rest arguments Option 

If a notification is received while in the input editor, function is called to handle 
it. function should take at least one argument, the notification (as returned by the 
rreceive-notification message to the stream), arguments are the remaining argu- 
ments to function, function can do anything it wants with the notification. To dis- 
play the notification, function would usually call sysrdisplay-notification. 

If this option is not specified, notifications appear one after the other using 
:insert-style typeout. 

Following are two simple examples of notification handlers. The first handler as- 
sumes that you want each notification to overwrite the previous one. The second 
handler assumes that you want them to appear one after another. *window* 
should be bound to a window and *stream* to a stream where you want the notifi- 
cations to appear. 

(defun my-notif ication-handler-1 (notification) 
(send xwindowx : clear-window) 
(sys:display-notif ication xwindowx notification :window)) 

(defun my-notif ication-handler-2 (notification) 

(sys:display-notif ication xstreamx notification :stream)) 



:partial-help &rest help-option Option 
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When the user presses HELP, the input editor first types out a message determined 
by help-option. It then types out a message describing how to invoke input editor 
commands and other information about the stream. If a :brief-help, 
:complete-help, or :merged-help option has been specified, it overrides rpartial- 
help. 

help-option can have one element, which can be a string, a function, or a symbol; 
or it can have more than one element. For an explanation: See the section "Dis- 
playing Help Messages in the Input Editor". 

This option is intended for use when inexperienced users might be typing to the 
input editor. Often help-option gives some information about the program to which 
the user is typing and what the user can do to exit from it. 



:pass-through &rest characters Option 

The characters in characters are not to be treated as special by the input editor. 
This option is used to pass format effectors (such as HELP or CLERR INPUT) 
through to the reading function instead of interpreting them as input editor com- 
mands. :pass-through is allowed only for characters with no modifier bits set, that 
is, for character codes through 377 (octal). For characters that have modifier 
bits set and must be visible to the reading function, use :do-not-echo or 
: activation. 



rpreemptable token Option 

A blip in the input stream causes control to be returned from the input editor im- 
mediately. Two values are returned: the blip and token, which is usually a keyword 
symbol. Any unscanned input typed before the blip remains in the input buffer, 
available to the next read operation from the stream. 



rprompt &rest prompt-option Option 

When it is time for the user to be prompted, the input editor displays prompt- 
option, prompt-option can have one element, which can be nil, a string, a function, 
or a symbol other than nil; or it can have more than one element: See the section 
"Displaying Prompts in the Input Editor". 

The difference between rprompt and rreprompt is that the latter does not display 
the prompt when the input editor is first entered, but only when the input is re- 
displayed (for example, after a screen clear). If both options are specified, 
rreprompt overrides rprompt except when the input editor is first entered. 



rreprompt &rest prompt-option Option 

When it is time for the user to be reprompted, the input editor displays prompt- 
option, prompt-option can have one element, which can be nil, a string, a function, 
or a symbol other than nil; or it can have more than one element: See the section 
"Displaying Prompts in the Input Editor". 
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Unlike rprompt, rreprompt displays the prompt only when input is redisplayed (for 
example, after a screen clear), not when the input editor is first entered. If both 
rprompt and rreprompt are specified, rreprompt overrides rprompt except when 
the input editor is first entered. 



rsuppress-notifications flag Option 

If a notification is received while in the input editor, and flag is supplied as nil, 
the input editor itself handles the notification, regardless of any other way you 
have specified that notifications should be handled. If flag is t, notifications are 
handled in the input editor the same way they would be handled if you were not in 
the input editor. That is, the input editor does not handle the notification itself. 



rinput-history-default string Option 

Specifies string as the default to be yanked by c-n-Y. string is temporarily placed 
at the head of the input history. If the user types c-n-Y n-Y, the true first ele- 
ment of the input history is yanked. c-n-S c-n-Y shows string at the head of the 
input history, and the entries in the input history are shifted down by one. 

In the following example, the user is prompted for a line of text. The input buffer 
is initially empty, but the c-n-Y command yanks a default, which is the name of 
the user. 

(with-input-edi ting-options 

(( : input-history-default fs: user-personal -name)) 
(prompt-and-read :string "Full name: ")) 

This option is used by the rpathname option for prompt-and-read. 

rinput-wait Specifiesafunctiontestingforsomeconditionwhilein 

the input-wait state. If this condition occurs, the rinput-wait- 
handler is invoked. 



rinput-wait-handler function &rest arguments Option 

When the input editor is waiting for input it sends the stream an rinput-wait 
message. After rinput-wait returns, the input editor applies function to arguments. 
The input editor does not process the input or display the notification until func- 
tion returns. 



(flavorrmethod rinsert-char tvrsheet) &optional (char-count 1) (unit 'rcharacter) 

Method 

Open up a space the width of char-count units in the current line at the current 
cursor position. Shift the characters to the right of the cursor further to the right 
to make room. Characters pushed past the right-hand edge of the window are lost. 
If unit is rcharacter, char-count is interpreted as the number of character-widths 
to insert; if unit is rpixel, char-count is interpreted as the number of pixels to in- 
sert. 
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(flavorrmethod :insert-item tvrtext-scroll-window) item-no new-item Method 

Inserts new-item into the item list before item-no. new-item can be any Lisp object. 
item-no is an item number, and should be a non-negative fixnum. 

If the item is inserted within the visible range, the window redisplays to show the 
new item. 



(flavorrmethod :insert-line tvrsheet) &optional (line-count 1) (unit 'rcharacter) 

Method 

Takes the line containing the cursor and all the lines below it, and moves them 
down by line-count units. A blank space (whose length is variable) is created at the 
cursor. Lines pushed off the bottom of the window are lost. If unit is rcharacter, 
line-count is interpreted as the number of lines to insert; if unit is rpixel, line- 
count is interpreted as the number of pixels to insert. 



(flavorrmethod rinsert-string tvrsheet) string &optional (start 0) (end nil) (type-too 
t) Method 

Inserts a string at the current cursor position, moving the rest of the line to the 
right to make room for it. 

The string to insert is specified by string; a substring thereof may be specified 
with start and end, as with rstring-out. 

If type-too is specified as nil, suppress the actual display of the string, and the 
space that was opened is left blank, rinsert-string, in this case, uses rinsert-char 
to actually make the space. 



(flavorrmethod rinside-edges tvrsheet) Method 

Returns four values: the left, top, right, and bottom inside edges, in pixels, relative 
to the top-left corner of this window. This can be useful for clipping. Note that 
this message is not analogous to the redges message, which returns the outside 
edges relative to the superior window. 



(flavorrmethod rinside-height tvrmenu) arg Init Option 

Specifies the inside height specified in pixels. Excludes margins. 

(flavorrmethod rinside-height tvrsheet) inside-height Init Option 

Specifies the inside height of the window. 

(flavorrmethod rinside-size tvrmenu) (inside-width inside-height) Init Option 

Specifies the inside size parameters specified in pixels. 
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(flavorrmethod :inside-size tvrsheet) Method 

Returns two values: the inside width and the inside height. 

(flavorrmethod :inside-size tvrsheet) (inside-width inside-height) Init Option 

Specifies the inside width and height of the window. 

(flavorrmethod rinside-width tvrmenu) arg Init Option 

Specifies the inside width of window in pixels. 

(flavorrmethod rinside-width tvrsheet) inside-width Init Option 

Specifies the inside width of the window. 



cprinstall-command command-table command-symbol &optional command-name 

Function 

Installs a Command Processor command into a command table. 

command-table Name (symbol or string) of the command table receiv- 

ing the new command. If it does not already exist, a command table 
will be created. 

command-symbol The command to install, a symbol. 

command-name The name of the command, a string. The default is the 

value supplied for the mame keyword argument in the command 
definition. 

For an overview of cprinstall-command and related facilities: See the section 
"Managing the Command Processor". 



(flavorrmethod rintegral-p tvrsheet) t-or-nil Init Option 

The default is nil. If this is specified as t, the inside dimensions of the window are 
made to be an integral number of characters wide and lines high, by making the 
bottom margin larger if necessary. 



rinteractive Message 

Returns t if the stream is interactive and nil if it is not. Interactive streams, built 
on sirinteractive-stream, are streams designed for interaction with human users. 
They support input editing. Use the rinteractive message to find out whether a 
stream supports the rinput-editor message. 
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sirinteractive-stream Flavor 

A stream that includes this flavor is interactive, or designed for interaction with a 
human user. In order to be useful, sirinteractive-stream must, in turn, include 
one of the following mixins: sirdisplay-input-editor, sirprinting-input-editor, or 
sirhalfduplex-input-editor. 

To find out whether or not a stream is interactive, send the stream an 
rinteractive message. 



dw:invalidate-type-handler-tables Function 

Invalidates presentation mouse handler lookup tables. The next time the tables are 
accessed, they are updated by this function to reflect any changes in the type hier- 
archy affecting handler applicability. 

This function gets called by the system whenever a new presentation type is de- 
fined. You need to call it directly only if your presentation-type definitions change 
dynamically at runtime, for example, through a global variable in the 
:abbreviation-for option. However, because the updating of the handler lookup 
tables does not occur in real time, you should avoid such usage. 

For an overview of dw:invalidate-type-handler-tables and related facilities: See 
the section "Programming the Mouse: Writing Mouse Handlers". 



(flavorrmethod :io-buffer tvrchoose-variable-values-window) buf Init Option 

Specifies the I/O buffer to be used. The buffer can be associated with another win- 
dow or it can be explicitly created for this window with the tv:make-io-buffer 
function. The I/O buffer is used both for reading keyboard input (new values) and 
for sending blips to the controlling process. 



(flavorrmethod :io-buffer tv:command-menu) buf Init Option 

The I/O buffer to be used by a command menu is usually specified when it is cre- 
ated. It can be shared with the I/O buffer of another window. I/O buffers are cre- 
ated with the tv:make-io-buffer function. 



(flavorrmethod :io-buffer tv:command-menu) Method 

gets the I/O buffer to which a command menu sends a command when an item is 
chosen. 



(flavorrmethod :io-buffer tv:constraint-frame-with-shared-io-buffer) io-buffer 

Init Option 

If this option is present, io-buffer is used as the I/O buffer for the frame and the 
panes. Otherwise, a default I/O buffer is created. 
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(flavorrmethod :item tv:basic-mouse-sensitive-items) type item &rest format-args 

Method 

Creates and displays a mouse-sensitive item of type type with associated object 
item. If format-args are supplied, they are a zlrformat control-string and argu- 
ments used to generate the display for this item. If format-args are not supplied, 
the display is generated with princ. 



(flavorrmethod ritem sirinteractive-stream) type item &rest format-args Method 

Creates and displays a (possibly mouse-sensitive) item of type type on the stream. 
If the stream does not support mouse-sensitivity, this just ignores type and displays 
item on the stream. If format-args are supplied, they are a format control string 
and control args to be used to display the item. Otherwise, the item is displayed 
by calling princ with a first argument of item. 



(flavorrmethod ritem tvrmouse-sensitive-text-scroll-window-without-click) item 
type &optional (function #'prinl) &rest print-args Method 

Creates a new mouse-sensitive item, item may be any lisp object, type is a keyword 
which specifies the type of item, function is the function which is used to display 
the item in the window, print-args are further arguments to function. 

This method prints item on the window at the current cursor position by calling 
function. The first argument to function is item; the second is the window itself; 
and the rest are the elements of print-args. 

The portion of the window printed on by this method becomes mouse-sensitive, and 
a box appears around it when the mouse is moved into that area. 



(flavorrmethod ritem-list tvrmenu) list Init Option 

Initializes the item list for a menu. See the section "Types of Menu Items". 

(flavorrmethod ritem-list-pointer tvrdynamic-...-menu) form Init Option 

The ellipses in the name (...) indicate that this option works with several flavors of 
dynamic menus. The form is saved and evaluated periodically to get the item-list 
for the menu, form is usually a special variable but any Lisp form is valid. The 
evaluation may occur in any process, so only global variables should be accessed. If 
the result of evaluating form is not zlrequal to the item list, the message rset- 
item-list is sent to the menu to update the new list. Note that the Lisp function 
equal is used for comparison, not eq. (Do not directly and destructively modify a 
menu's item list yourself; the system will do this automatically.) 

(flavorrmethod ritem-type-alist tvrbasic-mouse-sensitive-items) alist Init Option 
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Remembers alist as the set of item types allowed in this window, alist should be 
created by tv:add-typeout-item-type. 



(flavorrmethod :item-value tvrtext-scroll-window) item-no Method 

Returns the item whose number is item-no. 

(flavorrmethod ritems tvrtext-scroll-window) Method 

Returns the array that the window uses, internally, to hold the items. You should 
not modify the contents of this array or its fill pointer, because the window won't 
know that you did so, and redisplay will not work properly. 

sysrkbd-intercepted-characters Variable 

The value is a list of characters that are intercepted when they are read from an 
interactive stream. 

Bind this variable when you want to change the characters that the system inter- 
cepts. The default value is the value of sysrkbd-standard-intercepted-characters: 
(#\Abort #\m-Abort #\Suspend #\m-Suspend). sysrkbd-intercepted-characters is 
reset to this value on warm booting. You can bind sysrkbd-intercepted-characters 
to any subset of the default value, including nil, but you cannot include any char- 
acters that are not members of the default value. If you want the system to inter- 
cept only the standard abort characters, bind sysrkbd-intercepted-characters to 
the value of sysrkbd-standard-abort-characters. If you want the system to inter- 
cept only the standard break characters, bind sysrkbd-intercepted-characters to 
the value of sysrkbd-standard-suspend-characters. 

sysrkbd-standard-abort-characters Variable 

The value is a list of characters that are the default abort characters intercepted 
by the system. The default value is (#/Abort #/m-Abort). This is a constant. If you 
want the system to intercept only the standard abort characters, bind sysrkbd- 
intercepted-characters to the value of sysrkbd-standard-abort-characters. 

sysrkbd-standard-intercepted-characters Variable 

The value is a list of characters that is the default value of sysrkbd-intercepted- 
characters. The default value is (#/Abort #/m-Abort #/Suspend #/m-Suspend). 
This is a constant. If you want to change the characters that the system inter- 
cepts, bind sysrkbd-intercepted-characters, not sysrkbd-standard-intercepted- 
characters. 

sysrkbd-standard-suspend-characters Variable 
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The value is a list of characters that are the default suspend characters intercept- 
ed by the system. The default value is (#/Suspend #/m-Suspend). This is a con- 
stant. If you want the system to intercept only the standard suspend characters, 
bind sysrkbd-intercepted-characters to the value of sysrkbd-standard-suspend- 
characters. 



tv:key-state key-name Function 

Returns t if the keyboard key named key-name is currently pressed, nil if it is not. 

key-name may be the symbolic name of a modifier key, from the table below, or a 
character object. Modifier keys that come in pairs have three symbolic names; one 
for the left-hand key, one for the right-hand key, and one for both, which is con- 
sidered to be pressed if either member of the pair is. 

The modifier key names are: 



shift 

symbol 

control 

meta 

super 

hyper 

caps-lock 



left-shift :right-shift 

left-symbol : right-symbol 

left-control : right-control 

left-meta :right-meta 

left-super : right-super 

left-hyper : right-hyper 

repeat : mode-lock 



(flavorrmethod rlabel tvrchoose-variable-values) string Init Option 

The argument is a string that is the label displayed at the top of the window. The 
default is "Choose Variable Values". 



(flavorrmethod rlabel tvrlabel-mixin) specification Init Option 

Sets the string displayed as the label, the character style in which the label is 
displayed, and whether the label is at the top or the bottom of the window. Any- 
thing you don't specify will default; by default, the string is the same as the name 
of the window, the character style is the default character style for the screen, 
and the label is at the bottom of the window. 

specification may be any of: 

nil There is no label at all. 

t The label is given all the default characteristics. 

rtop The label is put at the top of the window. 

rbottom The label is put at the bottom of the window. 

a string The text displayed in the label is this string. 

a character style The label is displayed in the specified character style. 
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a list (keywordl argl keyword2 ...) The attributes corresponding to the key- 

words are set; the rest of the attributes default. Some keywords take argu- 
ments, and some do not. The following keywords may be given: 

:top The label is put at the top of the window. 

rbottom The label is put at the bottom of the window. 

rstring string The text displayed in the label is string. 

:character-style character-style The label is displayed in the specified 
character style, merged against the default character style. 

(flavorrmethod rlabel tvrmenu) specification Init Option 

Specifies the menu's label. The specification is usually a list in the following form: 
(: string "Foo" : style character-style-specification) 



tv:label-mixin Flavor 

Creates the labels in the corners of windows that you often see when using Gen- 
era. You can control the text of the label, the character style in which it is dis- 
played, and whether it appears at the top of the window or the bottom. 



(flavorrmethod :label-size tvrlabel-mixin) Method 

Returns the width and height of the area occupied by the label. 

cp : *last-command- values* Variable 

List of values returned by the most recently executed Command Processor com- 
mand. 

For an overview cpr*last-command- values* and related facilities, see the section 
"Managing the Command Processor". 

(flavorrmethod :last-item tvrtext-scroll-window) Method 

Returns the last item in the item list. 

time:leap-year-p year Function 

Returns t if year is a leap year; otherwise returns nil. year can be absolute or rel- 
ative to 1900 (that is, 84 and 1984 both work). 

(flavorrmethod rleft tvrmenu) arg Init Option 
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Specifies the left edge of the menu, defined in pixels relative to the outside of the 
superior window. 



(flavorrmethod :left tvrsheet) left-edge Init Option 

Specifies the x-coordinate of the left edge of the window, relative to the superior's 
coordinate system. 



(flavorrmethod :left-margin-size tvrsheet) Method 

Returns the left margin size of the window in pixels. 

(flavorrmethod rline-in sirinteractive-stream) &optional leader Method 

Reads characters from the stream and returns them as a string. If called from out- 
side the input editor, reads characters until a #\return, #\line, or #\end activation 
character is encountered. If called from inside the input editor, reads characters 
until a #\return delimiter is encountered. The activation or delimiter character is 
not part of the returned string. 

The method returns two values: the string and an eof flag. If the stream reaches 
end-of-file while reading characters, it returns the characters read as a string and 
returns a second value of t. Otherwise, the second returned value is nil. 

If leader is an integer, the returned string has an array leader of length leader, 
and the fill pointer is set to the location in the string following the last one read. 
Otherwise, the string has no array leader. 

Example: 

This feature is useful for debugging programs that read from noninteractive 
streams. For example, the following function reads a single line-oriented record, in 
which the first line is a decimal number saying how many lines are in the rest of 
the record. 

(defun read-record (&optional (stream standard-input)) 

(loop repeat (parse-number (send stream : line-in) nil 10.) 
collect (send stream :line-in))) 

If this function is invoked on an interactive stream, the input editor is enabled au- 
tomatically each time the rline-in message is sent, but it is not possible to edit 
across line boundaries. For example, once the number of lines in the record is 
typed, it is not possible to change it. 

(defun read-record (&optional (stream standard-input)) 
(with-input-editing (stream) 

(loop repeat (parse-number (send stream :line-in) nil 10.) 
collect (send stream :line-in)))) 

Wrapping a with-input-editing form around the body establishes a single input 
editing context for each record, with-input-editing has no effect when stream is a 
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noninteractive stream, so this same function may used for reading from a file or 
reading from an interactive stream. 



(flavorrmethod :line-out tvrsheet) string &optional (start 0) (end nil) Method 

Does the same thing as :string-out, and then advance to the next line (like typing 
a #\return character). The main reason that this message exists is so that the 
stream-copy-until-eof function can, under some conditions, move whole lines from 
one stream to another; this is more efficient than moving characters singly. The 
behavior of this operation is not affected by the :cr-not-newline-flag init option. 



tvrline-truncating-mixin Flavor 

An obsolete flavor that is the same as tv:truncatable-lines-mixin. The name is 
confusing; when this flavor is mixed in, truncation is enabled only if the window's 
truncate line out flag is on. Otherwise, it has no effect. tv:truncatable-lines-mixin 
is built on this flavor for the sake of two-argument zlrtypep. 

(flavorrmethod :list-tyi sirinteractive-stream) Method 

Like :any-tyi, except that it returns only blips, never integers. If it encounters any 
integers in the input stream, it discards them entirely (they are removed from the 
stream and the program never sees them). 

(flavorrmethod rlisten sirinteractive-stream) Method 

Returns t if there are any characters available to rany-tyi or rtyi, or nil if there 
are not. For example, the editor uses this to defer redisplay until it has caught up 
with all of the characters that have been typed in. 

(flavorrmethod rlisten tvrstream-mixin) Method 

Returns t if there are any characters available to rany-tyi or rtyi, or nil if there 
are not. For example, the editor uses this to defer redisplay until it has caught up 
with all the characters that have been typed in. 



tvrmake-blinker window &optional (flavor 'tvrrectangular-blinker) &rest options 

Function 

Creates and returns a new blinker. The new blinker is associated with the given 
window, and is of the given flavor. The options are initialization-options to the 
blinker flavor. All blinkers include the tvrblinker flavor, and so init options taken 
by tvrblinker will work for any flavor of blinker. Other init options may only work 
for particular flavors. See the section "General Blinker Operations" for other oper- 
ations on blinkers. See the section "Specialized Blinkers" for a list of other useful 
flavors of blinkers. 
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cp:make-command-table name &rest init-options &key (if-exists rerror) &allow- 
other-keys Function 

Creates and returns a Command Processor command table object. 

name The name (symbol or string) of the command table. 

init-options Keyword-values pairs that are init options to the (in- 

ternal) command-table flavor from which the command table object 
is created. Permissible options and values are as follows: 

:inherit-from Specifies a list of command tables 

(strings or objects) from which to inherit commands. 

:command-table-delims Specifies a list of characters to use as 
delimiters of words in command names for commands in 
the table. The default list is (#\Space #\Tab #\Return). 

:command-table-size An initial estimate of the number of 

commands the table will include (to preclude the table 
from having to grow substantially). 

:kbd-accelerator-p Boolean option specifying whether single- 

key accelerators may be used for commands; the default is 
t. Just because accelerators are defined does not mean 
that non-accelerated command reading is prohibited. 

: accelerator-case-matters Boolean option specifying whether single- 
key accelerators, if allowed, are case sensitive; the default 
is nil. 

:if-exists Specifies what happens if the command table named name already 
exists. Four values are possible: 

nil No new command table is made and the existing 

command table is returned. 

rsupersede The new command table is made and re- 

places the old command table. 

rupdate-options The existing command table remains but 

its options are updated to the newly specified init op- 
tions in the call to cp:make-command-table. 



rerror An error is signalled. 



Example: 



(cp: make-command-table "shel 1-cmds" : inherit-f rom '("user") 

:kbd-accelerator-p nil) 

For an overview of cprmake-command-table and related facilities: See the section 
"Managing the Command Processor". 
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make-mouse-char button &optional (bits 0) Function 

Constructs a mouse character given a mouse button number. 0, 1, and 2 corre- 
spond to the Left, Middle, and Right mouse buttons, respectively. 

The optional bits argument is a number encoding the shift keys qualifying the root 
mouse character as follows: 

Bits Shift Key 

None 

1 CONTROL 

2 METR 
4 SUPER 
8 HYPER 
16 SHIFT 

The shift keys are additive with respect to the bits value, for example: 

(make-mouse-char 31) ==> 
#\h-s-m-c-sh-Mouse-L 



tv:make-sheet-bit-array window width height &rest make-array-options Function 

Creates a two-dimensional bit-array useful for bitblting to and from windows. It 
makes an array whose first dimension is at least width but is rounded up so that 
bitblt's restriction regarding multiples of 32. is met, whose second dimension is 
height, and whose type is the same type as that of the screen array of window (or 
the type it would be if window had a screen array), make-array-options are passed 
along to zhmake-array when the array is created, so you can control other param- 
eters such as the area. 



tvrmake-window flavor-name &rest init-options Function 

Creates, initializes, and returns a new window of the specified flavor. The init- 
options argument is the init-plist (it is just like the &rest argument of make- 
instance). The allowed initialization options depend on what flavor of window you 
are making. Each window flavor handles some init options; the options and what 
they mean are documented with the documentation of the flavor. Note that 
:activate-p and :expose-p are keyword arguments which cannot be specified in the 
flavor's :default-init-plist. 

Example: 
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(defun make-window-example () 

(let ((window (tv: make-window 'tv: window 

:edges-from : mouse 

:expose-p t 

:bl inker-p t 

: def aul t-character-styl e 

' ( : f ix :bold : large) 
:save-bits t))) 
(format window "~2%Note the character style"))) 

The above function lets you specify the location of the upper-left and lower-right 
corners of the window with the mouse. Once the location is specified, the window 
is created and exposed. A blinker is visible; its size is that of the default character 
style for character output. Because the :save-bits init option is t, the formatted 
output to the window will still be visible after the window is de-exposed and then 
re-exposed. 

dwrmargin-borders Flavor 

Provides Dynamic Windows with a four-sided, black (or draw-alu color) border. 
dwrmargin-borders accepts the following init option: 

rthickness Specifies the thickness, in pixels, of the border; the de- 

fault is 1. 

For an overview of dwrmargin-borders and related facilities, see the section "Win- 
dow Substrate Facilities". 



tvrmargin-choice-mixin Flavor 

Puts choice boxes in the bottom margin, according to a list of choice-box descrip- 
tors that can be specified with the rmargin-choices init-plist option or the rset- 
margin-choices message. The choice boxes are spread evenly across the bottom 
margin. 

A choice-box descriptor is a list, defined as follows: 

(name state function xl x2) 

You can use a longer list as a choice-box descriptor and store your own data in the 
additional elements. 

name is a string that labels the box. state is t if the box has an "X" in it, or nil if 
it is empty. 

function is a function called by the system in a separate process if the user clicks 
on the choice box. It receives four arguments: the window containing the choice 
box, the choice-box descriptor for the choice box, the "margin region" that contains 
the choice boxes, and the Y position of the mouse relative to this window. (The 
last two arguments are usually ignored.) 
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The structure access functions tv:choice-box-name and tv:choice-box-state may be 
of use inside function (they are just more specific names for car and cadr). If 
function changes the state of the choice box, it should refresh the choice boxes in 
the following way: 

(send (tv: margin-region-function region) : refresh window region) 

where region is its third argument. This is why the region argument is passed. 
Note that automatic implications of a choice (things that happen to the other 
choice boxes when one choice box is selected), such as in the multiple choice facili- 
ty are not implemented in the margin-choice facility. See the section "The Multiple 
Choice Facility". Programmers must write their own implication routines. 

xl and x2 are used internally to remember the location of the choice boxes. 

tv:margin-choice-mixin is built on the non-instantiable flavor tvrmargin-region- 
mixin; the position of the latter in the list of component flavors controls where in 
the margins the choice boxes appear. The default puts tv:margin-region-mixin 
right after tv:margin-choice-mixin. To place the choice boxes inside the borders, 
use the following model: 

(defflavor bordered-window-with-margin-choices () 

(tv: borders-mi xin tv:margin-choice-mixin tv:window) 



(flavorrmethod rmargin-choices tvrchoose-variable-values) list Init Option 

The argument is a list of specifications for choice boxes to appear in the bottom 
margin. Each element can be a string, which is the label for the box that means 
"done," or a list containing a label string and a form to be evaluated if that choice 
box is clicked on. Since this form is evaluated in the user process it can do such 
things as alter the values of variables or zlr*throw out. With this facility, the de- 
fault for rmargin-choices is [Exit]. For an explanation of margin choices and their 
use, see the section "The Margin Choice Facility". 



(flavorrmethod rmargin-choices tvrchoose-variable-values-window) choice-list 

Init Option 

The default is a single choice box, labelled [Done]. For an explanation of the 
choice-box descriptors, see the section "The Margin Choice Facility". Note that 
specifying nil for this option suppresses the margin-choices entirely. 



(flavorrmethod rmargin-choices tvrmargin-choice-mixin) choices Init Option 

Causes a line of choice-boxes to appear in the bottom margin of the window, choic- 
es is a list of choice-box descriptors, described previously. If choices is nil, there 
are no choice boxes and no space for them in the bottom margin; however, the 
window is still capable of accepting the r set-margin-choices message to create a 
line of choice boxes later. 
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dw:margin-drop-shadow-borders Flavor 

Provides Dynamic Windows with a black (normal video) border shadowed on its 
right and bottom margins by a gray border. 

dw:margin-drop-shadow-borders accepts the following init options: 

:non-shadow-thickness Specifies the thickness, in pixels, of the 

black border; the default is 3. 

routside-margin Specifies the thickness, in pixels, of whitespace sur- 

rounding the shadowed and non-shadowed borders of the box; the 
default is 0. 

: shadow- thickness Specifies the thickness, in pixels, of the gray margins 
on the right and bottom edges of the window; the default is 8. 

For an overview of dw:margin-drop-shadow-borders and related facilities, see the 
section "Window Substrate Facilities". 

dw:margin-label Flavor 

Specifies Dynamic Window labels. 
dw:margin-label accepts the following init options: 

:background-gray Specifies a binary array to use as a background pattern 
for the label. 

You can provide your own array via the tv:make-binary-array func- 
tion — for an example, see the dictionary entry for graphicsrdraw- 
pattern — or use one of the standard, background-gray patterns: 
stipples:25%-gray, stipples:33%-gray, stipples:50%-gray, or 
stipples: 75%-gray. 

Note that the specification is for an array object, not its symbol. 

:box Specifies whether to enclose the label in a box; the default is nil. 

Other permissible values are rinside and routside. If you wish to 
box the label within a just-specified border, use rinside; if you wish 
to box the label outside of a border about to be specified, use 
routside. 

rbox-thickness Specifies the thickness, in pixels, of the line used to 

draw a box around the label when the rbox init option is non-nil. 

rcentered-p Boolean option specifying whether the label is left-right 

centered. The default is nil, causing the label to appear on the left 
side of the margin. 

rextend-box-p Boolean option specifying whether the box drawn 

(when the rbox option is non-nil) extends the full length of the mar- 
gin or is limited to the length of the label; the default is t. 
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rmargin Specifies the margin, :top or rbottom, on which the label appears; 
the default is rbottom. 

rstring Specifies the label string. The default string is derived from the 
name of the window flavor used to make the window instance. 

rstyle Specifies the character style used for writing the label string. The 
default value is the character- style default for the screen. 

rcharacter-style Specifies the character style used for writing the label 

string. The default value is the character- style default for the 
screen, rcharacter-style and rstyle are different names for the same 
option (for back-compatibility). 

After a window instance is created, you can change its label by using 
(flavorrmethod rset-label dwrmargin-mixin). 

For an overview of dwrmargin-label and related facilities: See the section "Win- 
dow Substrate Facilities". 



dwrmargin-ragged-borders Flavor 

Provides Dynamic Windows with a ragged (wavy) border to indicate that more out- 
put can be viewed by scrolling in the direction indicated. The border is only 
ragged when there is in fact more output to be viewed; otherwise, it is straight. 

dwrmargin-ragged-borders accepts the following init options: 

rhorizontal-too Boolean option specifying whether to provide ragged 

left and right margins in addition to ragged top and bottom mar- 
gins; the default is t. 

rthickness Specifies the thickness, in pixels, of the border; the de- 

fault is 2. 

For an overview of dwrmargin-ragged-borders and related facilities, see the sec- 
tion "Window Substrate Facilities". 



dwrmargin-scroll-bar Flavor 

Provides an "elevator" scroll bar to a Dynamic Window. 
dwrmargin-scroll-bar accepts the following init options: 

relevator-thickness Specifies the overall width, in pixels, of the scroll bar; 
the default is 10. 

rhistory-noun Specifies a string appearing as part of the mouse docu- 

mentation when the mouse cursor is moved over the scroll bar. The 
specified string is substituted for the word "history", the default 
value for this option. 
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For example, if you specified "graphic output", when the window 
was created and the user positioned the mouse cursor in the middle 
of the scroll bar, the mouse documentation line would read, "... 
Middle: Move to 50% of graphic output..." instead of "... Middle: 
Move to 50% of history..." 

rmargin Specifies the margin — :left, rright, :top, or rbottom — on which 
the scroll bar appears; the default is :left. 

rshaft-whitespace-thickness Specifies the thickness, in pixels, of addi- 

tional whitespace (normal video) inserted on each side of the scroll 
bar between it and the neighboring component. The default is 0, 
causing the whitespace to be one-pixel-wide on both sides. 

rvisibility 

Specifies when the scroll bar is visible. Three values are permitted: 

rnormal The scroll bar appears when the flavor is instantiated and 
remains visible regardless of whether it is needed. This is 
the default. 

:if-requestedAn empty elevator shaft appears when the flavor is in- 
stantiated and after each new output operation to the 
window. If the user moves the mouse cursor into the 
scroll bar area, the standard cross-hatched pattern is 
drawn in the shaft and the scroll bar becomes normally 
active. 

:if-needed The scroll bar does not appear until the output exceeds 
the window space available for displaying it, that is, until 
the need for scrolling arises; thereafter it remains visible 
and normally active. The space needed for drawing the 
scroll bar is reserved by whitespace (normal video) until 
the scroll bar appears. 

For an overview of dw:margin-scroll-bar and related facilities: See the section 
"Window Substrate Facilities". 



tv:margin-scroll-mixin Flavor 

Provides scrolling by clicking on margin regions. 

(flavorrmethod rmargin-scroll-regions tv:margin-scroll-mixin) regions Init Option 
Allows you to specify the messages at the top and bottom of the display. 
regions is a list of lists. Each list contains four elements: 

• :top or rbottom. 
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• A string that displays at the end of the item list in the given direction. 

• A string that displays when there are more items to display in the given direc- 
tion. 

• The character style that the string prints in. 

The keyword :top is identical to the list: 

(:top "Top" "More above" (: dutch : italic :small)) 

The Keyword rbottom is identical to the list: 

(: bottom "Bottom" "More below" (: dutch : italic :small)) 



tv:margin-scrolling-with-flashy-scrolling-mixin Flavor 

Provides More above and More below style window scrolling for a text scroll win- 
dow. 



(flavorrmethod :margin-space tv:margin-space-mixin) Init Option 

Initializes the amount of blank space in the margins of the window. Possible val- 
ues: 

nil No space 

t One pixel blank in each of the four margins 

n n pixels of space in each of the four margins (n is an integer) 

(left top right bottom) left pixels blank in the left margin, top pixels blank in 

the top margin, and so on (values are integers) 



(flavorrmethod rmargin-space tvrmargin-space-mixin) Method 

Returns a list of four elements, (left top right bottom). These are integers repre- 
senting the number of pixels of blank space in the four margins of the window. 



tvrmargin-space-mixin Flavor 

Provides a margin item that just leaves some blank space. It might be useful if 

you're using scroll bars, and you want to leave a little white space between the 
scroll bar and the inside of the window. 



(flavorrmethod rmargins tvrsheet) Method 

Returns four values: the sizes of the left, top, right, and bottom margins, respec- 
tively. 
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dw:margin-white-borders Flavor 

Provides Dynamic Windows with a four-sided, white (or erase-alu color) border. 
dw:margin-white-borders accepts the following init option: 

rthickness Specifies the thickness, in pixels, of the border; the de- 

fault is 1. 

For an overview of dw:margin-white-borders and related facilities, see the section 
"Window Substrate Facilities". 

dwrmargin-whitespace Flavor 

Provides Dynamic Windows with whitespace (or erase-alu color) on a margin. 

dwrmargin-whitespace accepts the following init options. Note that the rmargin 
must be specified or else an error results. 

rmargin Specifies the margin, one of rleft, rright, rtop, or rbottom. 

rthickness Specifies the thickness, in pixels, of the border; the de- 

fault is 1. 

For an overview of dwrmargin-whitespace and related facilities, see the section 
"Window Substrate Facilities". 

tvrmenu Flavor 

This is tvrbasic-menu with borders and an optional label on top. By default, there 
is no label, but you can specify one with the rlabel init-plist option or the rset- 
label message, tvrmenu is built on the tvrbasic-menu, tvrborders-mixin, tvrtop- 
box-label-mixin, tvrbasic-scroll-bar, and tvrminimum-window flavors. 



dwrmenu-choose item-list &key (prompt nil) (default nil) (presentation-type nil) 
(printer nil) (near-mode '(rmouse)) (superior tvrmouse-sheet) (center-p 
dwrr*default-menu-center-p*) (character-style '(rjess rroman rlarge)) (momentary-p 
t) (temporary-p dwrrmomentary-p) (alias-for-selected-windows nil) (minimum-width 
nil) (minimum-height nil) Function 

Constructs a menu from a list of items and returns the value associated with the 
selected item; also returned are the item and the mouse character that was used 
to select it. 

item-list A quoted list of items to include in the menu display. A menu item 
can have various forms: See the section "The Form of a Menu 
Item". 

If you wish to control the mouse documentation associated with an 
item, use the "general list" form and include the r documentation 
menu-item option. 
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Example: 

(dw: menu-choose '(("First Choice" :value 1 

: documentation "Mouse Doc One") 
("Second Choice" :value 2 
: documentation "Mouse Doc Two"))) 

The other available menu-item option is rstyle, specifying the char- 
acter style of the individual item. This contrasts with the 
:character-style option to dwrmenu-choose as a whole, which speci- 
fies the style for all items. If both are specified, the locally specified 
rstyle prevails. For an example, see the rcharacter-style option; de- 
scriptions of this and other options to dwrmenu-choose follow. 

rprompt Specifies a string to use as a title for the menu. The menu title ap- 
pears at the top of the menu. 

rdefault Specifies an item in the item-list that is the currently selected 
(highlighted) item when the menu is first displayed. 

If the item list is a simple one containing symbols, then specify the 
default item by its symbol as shown below: 

Simple example: 

(dw:menu-choose ' (a b c) :default 'a) 

If the items are themselves lists, then supply the default item in a 
fashion similar to that shown in the following example. (That is, be 
sure to specify an item, not the item's value. The default you speci- 
fy must be eq to the item.) 

(setq item-list '(("One" :value 1) ("Two" :value 2))) 
(dw:menu-choose item-list :default (first item-list)) 

rpresentation-type Specifies the presentation type of the items presented 
in the menu. This results in the printer for that presentation type 
being used to display the items in the menu. 

Because each item (element) in item-list is passed to the presenta- 
tion type's printer, using this option is, in general, only appropriate 
when item-list is a simple list of objects (as opposed to a "general 
list"). In this case, you might also consider using dwrmenu-choose- 
from-set rather than dwrmenu-choose. 



rprinter Specifies a function of two arguments for printing the menu items. 
The arguments are an object — one element of the item-list — and 
a stream. If both this option and the rpresentation-type option are 
specified, the printer used is the one specified by this option, not 
that of the presentation type. 

Example: 
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(dw: menu-choose '((a :value test) 
(b :value 17)) 
:printer 

#' (lambda (object stream) 
(format stream 

"xxx~Axxx" (car object)))) 

The example function pops up a menu displaying two choices, 
"xxxAxxx" and "xxxBxxx". Clicking on "xxxAxxx" returns TEST; 
clicking on "xxxBxxx" returns 17. 

:near-mode Specifies where the menu appears. The default makes 

it appear near the position of the mouse cursor at the time the 
function is called. For other possibilities: See the method 
(flavor rmethod :expose-near tv:essential-set-edges). 

rsuperior Specifies the window that is the superior of the menu window; the 
default is tv:mouse-sheet. 

:center-p Boolean option specifying whether items displayed in the menu are 
centered, left to right. The default is nil, which causes the items to 
be flush left. 

:character-style Specifies the character style for display of menu items. 

The default is Gjess :roman :large). 

If the rstyle option for an individual item is specified, this locally 
overrides the :character-style specified for the menu as a whole, 
but does not affect other items. The example below illustrates this: 

(dw:menu-choose '(("First Choice" :value 1 

: style (nil nil : normal)) 
("Second Choice" :value 2)) 
: character-style 

'(:serif :bold : very-large)) 

:momentary-p Boolean option specifying whether the menu is momen- 

tary or temporary; the default is momentary. If you wish to make 
the menu temporary, supply a value of nil to this option and t to 
the :temporary-p option. 

A momentary window is deactivated and returns a value of nil if 
the user moves the mouse cursor off the menu. A temporary menu 
remains active until the user selects a menu item. 

:temporary-p Boolean option specifying whether the menu is tempo- 

rary or momentary; the default is momentary. If you wish to make 
the menu temporary, supply a value of t to this option and nil to 
the :momentary-p option. 
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A momentary window is deactivated and returns a value of nil if 
the user moves the mouse cursor off the menu. A temporary menu 
remains active until the user selects a menu item. 

:alias-for-selected-windows Specifies the activity to be returned by 

the menu in response to the :alias-for-selected-windows window 
message. The default value, nil, specifies that the menu should re- 
turn itself. 

Using :alias-for-selected-windows allows you to join the menu to 
another activity, as opposed to having the menu be an activity in its 
own right. This causes Function S to select a different activity 
when invoked while the menu is popped up, instead of selecting the 
window under the menu. 

For example, if you type 

(dw:menu-choose-f rom-set ' (a b c) 'symbol 

:al ias-for-selected-windows xterminal-iox) 

from the Lisp Listener, and issue a FUNCTION S command while the 
menu is present, you will select the window that was selected just 
before the Lisp Listener. If you had taken the default for :alias-for- 
selected- windows, FUNCTION S over the window would have selected 
the Lisp Listener. 

:minimum-width Specifies the minimum width of the menu in pixel 

units. The default, nil, causes the width of the window to be only as 
wide as is necessary to contain the menu items. 

rminimum-height Specifies the minimum height of the menu in pixel 

units. The default, nil, causes the width of the window to be only 
as high as is necessary to contain the menu items. 

For an overview of dwrmenu-choose and related facilities: See the section "Using 
Presentation Types for Input". 



tvrmenu-choose item-list &optional label near-mode default-item Function 

item-list is a list of menu items. See the section "Types of Menu Items". This func- 
tion pops up a menu and allows the user to make a choice with the mouse. When 
the choice is made, the menu disappears and the chosen item is executed. The val- 
ue of that item is returned. If the user moves the mouse out of the menu and far 
away, it pops down without making any choice and nil is returned. 

label is a string to be displayed at the top of the menu, or nil (the default) to 
specify the absence of a label. 

near-mode specifies where to put the menu on the screen. It defaults to the list 
(rmouse) and must be an acceptable argument to tv:expose-window-near. 
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default-item is the item over which the mouse should be positioned initially. This 
allows the user to select that item without moving the mouse. If default-item is nil 
or unspecified, the mouse is initially positioned in the center of the menu. 



dw:menu-choose-from-copy-of-window-contents window presentation-type &key 
.■prompt .-default (mear-mode '(:mouse)J (superior (tvrmouse-default-superior 
dw::window)J (:momentary-p t) (:temporary-p dw::momentary-p) Function 

Displays a pop-up copy of window and chooses an item of presentation-type from it. 
Similar to dw:menu-choose-from-set. 

window A window, typically, a menu pane of a program frame. 
presentation-type The presentation type used to present the objects. 

Here is an example taken from the graphic editor: 

(def i ne-presentati on-to-command-transl ator pop-up-shapes-menu 
(graphic-input: grid-output 
:blank-area t :menu () 

: gesture : pop-up-shapes-menu ; :menu 
documentation "Shapes menu") 
(ignore &key window x y) 
(when (drawing-window-point-p window x y) 
(if dw:*insi de-handler- test-phase* 
1 (com-create-entity) 
(let* ((frame (send window :superior)) 

(shape (dw : menu-choose-f rom-copy-of-wi ndow-contents 

(send frame : get-pane 'shapes-menu) 'entity-shape 
:prompt "Create a shape" :superior frame))) 
(if (null shape) 

(signal 'sys: abort) 

1 (com-create-enti ty , shape) ) ) ) ) ) 

rprompt Specifies a string to use as a title for the menu. The menu title ap- 
pears at the top of the menu. 

rdefault Specifies an item to be the currently selected (highlighted) item 
when the menu is first displayed. 

Examples: 

(dw:menu-choose-f rom-set ' (a b c) 'symbol :default 'a) 



(setq item-list '("One" "Two")) 
(dw:menu-choose-f rom-set item-list 'string 

:default (first item-list)) 

mear-mode Specifies where the menu appears. The default makes 

it appear near the position of the mouse cursor at the time the 
function is called. For other possibilities: See the method 



Page 1304 



(flavor rmethod :expose-near tv:essential-set-edges). 

rsuperior Specifies the window that is the superior of the menu window; the 
default is tv:mouse-sheet. 

:momentary-p Boolean option specifying whether the menu is momen- 

tary or temporary; the default is momentary. If you wish to make 
the menu temporary, supply a value of nil to this option and t to 
the :temporary-p option. 

A momentary window is deactivated and returns a value of nil if 
the user moves the mouse cursor off the menu. A temporary menu 
remains active until the user selects a menu item. 

:temporary-p Boolean option specifying whether the menu is tempo- 

rary or momentary; the default is momentary. If you wish to make 
the menu temporary, supply a value of t to this option and nil to 
the :momentary-p option. 

A momentary window is deactivated and returns a value of nil if 
the user moves the mouse cursor off the menu. A temporary menu 
remains active until the user selects a menu item. 



dw:menu-choose-from-copy-of-window-contents window presentation-type &key 
.■prompt .-default (mear-mode '(:mouse)J (superior (tvrmouse-default-superior 
dw::window)J (:momentary-p t) (:temporary-p dw::momentary-p) Function 

Displays a pop-up copy of window and chooses an item of presentation-type from it. 
Similar to dw:menu-choose-from-set. 

window A window, typically, a menu pane of a program frame. 
presentation-type The presentation type used to present the objects. 

Here is an example taken from the graphic editor: 
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(def i ne-presentati on-to-command-transl ator pop-up-shapes-menu 
(graphic-input: grid-output 
:blank-area t :menu () 

: gesture : pop-up-shapes-menu ; :menu 
: documentation "Shapes menu") 
(ignore &key window x y) 
(when (drawing-window-point-p window x y) 
(if dw:*insi de-handler- test-phase* 
1 (com-create-entity) 
(let* ((frame (send window :superior)) 

(shape (dw : menu-choose-f rom-copy-of-wi ndow-contents 

(send frame : get-pane 'shapes-menu) 'entity-shape 
:prompt "Create a shape" :superior frame))) 
(if (null shape) 

(signal 'sys: abort) 

1 (com-create-enti ty , shape) ) ) ) ) ) 

rprompt Specifies a string to use as a title for the menu. The menu title ap- 
pears at the top of the menu. 

rdefault Specifies an item to be the currently selected (highlighted) item 
when the menu is first displayed. 

Examples: 

(dw:menu-choose-f rom-set ' (a b c) 'symbol :default 'a) 

(setq item-list '("One" "Two")) 
(dw:menu-choose-f rom-set item-list 'string 

:default (first item-list)) 

:near-mode Specifies where the menu appears. The default makes 

it appear near the position of the mouse cursor at the time the 
function is called. For other possibilities: See the method 
(flavor rmethod :expose-near tv:essential-set-edges). 

rsuperior Specifies the window that is the superior of the menu window; the 
default is tv:mouse-sheet. 

:momentary-p Boolean option specifying whether the menu is momen- 

tary or temporary; the default is momentary. If you wish to make 
the menu temporary, supply a value of nil to this option and t to 
the :temporary-p option. 

A momentary window is deactivated and returns a value of nil if 
the user moves the mouse cursor off the menu. A temporary menu 
remains active until the user selects a menu item. 



:temporary-p Boolean option specifying whether the menu is tempo- 

rary or momentary; the default is momentary. If you wish to make 
the menu temporary, supply a value of t to this option and nil to 
the :momentary-p option. 
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A momentary window is deactivated and returns a value of nil if 
the user moves the mouse cursor off the menu. A temporary menu 
remains active until the user selects a menu item. 



dw:menu-choose-from-drawer drawer presentation-type &key .-prompt .-default 
(-.near-mode '(:mouse)J (.superior (tv:mouse-default-superior)J :alias-for-selected- 
windows (:row-wise t) (:center-p dw::*default-menu-center-p*) (-character-style 
dw::*default-menu-character-style*J (:momentary-p t) (:temporary-p 

dw::momentary-p) (-use-redisplay t) .-minimum-width .-minimum-height Function 

Constructs a menu from a collection of presentations produced by drawer of pre- 
sentation type presentation-type and returns the selected object. This function is 
similar to dw:menu-choose-from-set. 



drawer A function that returns a set of presentations. It is funcalled (per- 
haps several times, within redisplayer) given stream and the key- 
word arguments :max-width and :max-height. For example: 

#' (lambda (stream &rest ignore) 

(loop for item in handler-list 
col lect 

(present item presentation-type 
: stream stream 
:single-box t 

:al low-sensitive-inferiors nil 
:al low-sensitive-raw-text nil) 
do (send stream :tyo #\return))) 

presentation-type The presentation type used to present the objects (but 

see the rprinter option below). 

rprompt Specifies a string to use as a title for the menu. The menu title ap- 
pears at the top of the menu. 

rdefault Specifies an item to be the currently selected (highlighted) item 
when the menu is first displayed. 

Examples: 

(dw:menu-choose-f rom-set ' (a b c) 'symbol :default 'a) 



(setq item-list '("One" "Two")) 
(dw:menu-choose-f rom-set item-list 'string 

:default (first item-list)) 

:near-mode Specifies where the menu appears. The default makes 

it appear near the position of the mouse cursor at the time the 
function is called. For other possibilities: See the method 
(flavor rmethod :expose-near tv:essential-set-edges). 
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rsuperior Specifies the window that is the superior of the menu window; the 
default is tv:mouse-sheet. 

:alias-for-selected-windows Specifies the activity to be returned by 

the menu in response to the :alias-for-selected-windows window 
message. The default value, nil, specifies that the menu should re- 
turn itself. 

Using :alias-for-selected-windows allows you to join the menu to 
another activity, as opposed to having the menu be an activity in its 
own right. This causes Function S to select a different activity 
when invoked while the menu is popped up, instead of selecting the 
window under the menu. 

For example, if you type 

(dw:menu-choose-f rom-set ' (a b c) 'symbol 

:al ias-for-selected-windows xterminal-iox) 

from the Lisp Listener, and issue a FUNCTION S command while the 
menu is present, you will select the window that was selected just 
before the Lisp Listener. If you had taken the default for :alias-for- 
selected- windows, FUNCTION S over the window would have selected 
the Lisp Listener. 

:row-wiseA Boolean specifying when t, that the menu items are to be dis- 
played row-wise. 

:center-p Boolean option specifying whether items displayed in the menu are 
centered, left to right. The default is nil, which causes the items to 
be flush left. 

:character-style Specifies the character style for display of menu items. 

The default is (:jess :roman :large). 

:momentary-p Boolean option specifying whether the menu is momen- 

tary or temporary; the default is momentary. If you wish to make 
the menu temporary, supply a value of nil to this option and t to 
the :temporary-p option. 

A momentary window is deactivated and returns a value of nil if 
the user moves the mouse cursor off the menu. A temporary menu 
remains active until the user selects a menu item. 

:temporary-p Boolean option specifying whether the menu is tempo- 

rary or momentary; the default is momentary. If you wish to make 
the menu temporary, supply a value of t to this option and nil to 
the :momentary-p option. 

A momentary window is deactivated and returns a value of nil if 
the user moves the mouse cursor off the menu. A temporary menu 
remains active until the user selects a menu item. 
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:use-redisplay A Boolean specifying when t that the menu is to be 

displayed redisplayably. 

:minimum-width Specifies the minimum width of the menu in pixel 

units. The default, nil, causes the width of the window to be only as 
wide as is necessary to contain the menu items. 

rminimum-height Specifies the minimum height of the menu in pixel 

units. The default, nil, causes the width of the window to be only 
as high as is necessary to contain the menu items. 



dw:menu-choose-from-set list presentation-type &key (printer nil) (prompt nil) (de- 
fault nil) (near-mode '(rmouse)) (superior tv:mouse-sheet) (center-p dw::*default- 
menu-center-p*) (character-style '(:jess rroman rlarge)) (momentary-p t) (tempo- 
rary-p dw::momentary-p) (alias-for-selected-windows nil) (minimum-width nil) 
(minimum-height nil) Function 

Constructs a menu from a list of objects of a specified presentation type and re- 
turns the selected object. 

This function is similar to dwrmenu-choose, but is intended primarily for present- 
ing a simple list of items in menu format, not items of the "general list" form that 
dwrmenu-choose handles. 

list The list of objects. 

presentation-type The presentation type used to present the objects (but 

see the rprinter option below). 

Examples: 

(dw:menu-choose-f rom-set ' (a b c) 'symbol) 

(dw : menu-choose- from-set ' (ftp" sys: site; foo.bar" 
#p"y :>doughty>a.b") 'pathname) 

(setq item-list '("One" "Two")) 
(dw:menu-choose-f rom-set item-list 'string) 

rprinter Specifies a function of two arguments for printing menu items. The 
arguments are an object — one element of list — and a stream. If 
specified, this printer is used for displaying menu items rather than 
that of the specified presentation-type. 

Example: 
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(dw:menu-choose-f rom-set ' (#p"sys:site;conf ig.data" 
#p"y :>doty>examples. 1 isp") 'pathname 
:printer 

#' (lambda (object stream) 
(write-string 

(send object :name) 
stream))) 

The example function creates a menu displaying the choices "CON- 
FIG" and "EXAMPLES". Pathname objects are still returned when 
clicked on; just the appearance in the menu has changed. 

rprompt Specifies a string to use as a title for the menu. The menu title ap- 
pears at the top of the menu. 

rdefault Specifies an item to be the currently selected (highlighted) item 
when the menu is first displayed. 

Examples: 

(dw:menu-choose-f rom-set ' (a b c) 'symbol :default 'a) 

(setq item-list '("One" "Two")) 
(dw:menu-choose-f rom-set item-list 'string 

:default (first item-list)) 

:near-mode Specifies where the menu appears. The default makes 

it appear near the position of the mouse cursor at the time the 
function is called. For other possibilities: See the method 
(flavor rmethod :expose-near tv:essential-set-edges). 

rsuperior Specifies the window that is the superior of the menu window; the 
default is tv:mouse-sheet. 

:center-p Boolean option specifying whether items displayed in the menu are 
centered, left to right. The default is nil, which causes the items to 
be flush left. 

:character-style Specifies the character style for display of menu items. 

The default is (:jess :roman :large). 

:momentary-p Boolean option specifying whether the menu is momen- 

tary or temporary; the default is momentary. If you wish to make 
the menu temporary, supply a value of nil to this option and t to 
the :temporary-p option. 

A momentary window is deactivated and returns a value of nil if 
the user moves the mouse cursor off the menu. A temporary menu 
remains active until the user selects a menu item. 
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:temporary-p Boolean option specifying whether the menu is tempo- 

rary or momentary; the default is momentary. If you wish to make 
the menu temporary, supply a value of t to this option and nil to 
the :momentary-p option. 

A momentary window is deactivated and returns a value of nil if 
the user moves the mouse cursor off the menu. A temporary menu 
remains active until the user selects a menu item. 

:alias-for-selected-windows Specifies the activity to be returned by 

the menu in response to the :alias-for-selected-windows window 
message. The default value, nil, specifies that the menu should re- 
turn itself. 

Using :alias-for-selected-windows allows you to join the menu to 
another activity, as opposed to having the menu be an activity in its 
own right. This causes Function S to select a different activity 
when invoked while the menu is popped up, instead of selecting the 
window under the menu. 

For example, if you type 

(dw:menu-choose-f rom-set ' (a b c) 'symbol 

:al ias-for-selected-windows xterminal-iox) 

from the Lisp Listener, and issue a FUNCTION S command while the 
menu is present, you will select the window that was selected just 
before the Lisp Listener. If you had taken the default for :alias-for- 
selected- windows, FUNCTION S over the window would have selected 
the Lisp Listener. 

:minimum-width Specifies the minimum width of the menu in pixel 

units. The default, nil, causes the width of the window to be only as 
wide as is necessary to contain the menu items. 

rminimum-height Specifies the minimum height of the menu in pixel 

units. The default, nil, causes the width of the window to be only 
as high as is necessary to contain the menu items. 

For an overview of dw:menu-choose-from-set and related facilities: See the sec- 
tion "Using Presentation Types for Input". 



(flavorrmethod :menu-highlighted-items tv:menu-highlighting-mixin) Method 

Get the list of highlighted items. 

tv:menu-highlighting-mixin Flavor 

Allows some of the menu items to be highlighted with inverse video. This is typi- 
cally used with menus of options, where the options currently in effect are high- 
lighted. The menu items corresponding to modes are typically set up so that when 
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executed, they adjust the highlighting to reflect the enabling or disabling of a 
mode. 



:merged-help function &rest arguments Option 

When the user presses HELP, the input editor types out a message determined by 
the arguments, function is a function that takes at least two arguments. The input 
editor calls the function to print the help message. The first argument is the 
stream. The second argument is a continuation (a list) to print a standard message 
describing how to invoke input editor commands and other information about the 
stream. When the function wants to print this message, it should apply the car of 
the continuation to the cdr. If any arguments are supplied, they are the remaining 
arguments to the function. 

If a :brief-help or :complete-help option has been specified, it overrides rmerged- 
help. :merged-help overrides :partial-help. 

This option is intended for programs that want to decide when and where to dis- 
play their own help messages and the standard help message. 



(flavorrmethod rminimum-height tvressential-window) n-pixels Init Option 

In combination with the :edges-from rmouse init option, this option and 
:minimum-width specify the minimum size of the rectangle accepted from the 
user. If the user tries to specify a size smaller than one or both of these minima, 
the console will beep or flash, and the user will be prompted to start over again 
with a new top-left corner. 



(flavorrmethod rminimum-height tvrmenu) arg Init Option 



(flavorrmethod rminimum-width tvressential-window) n-pixels Init Option 

In combination with the redges-from rmouse init option, this option and 
rminimum-height specify the minimum size of the rectangle accepted from the 
user. If the user tries to specify a size smaller than one or both of these minima, 
the console will beep or flash, and the user will be prompted to start over again 
with a new top-left corner. 



(flavorrmethod rminimum-width tvrmenu) arg Init Option 

In combination with the redges-from rmouse init option, rminimum-height and 

rminimum-width specify the minimum size (in pixels) of the rectangle accepted 
from the user. If the user tries to specify a size smaller than one or both of these 
minimums, the screen beeps and the system prompts the user with a new left- 
corner. 



Page 1312 



tv:momentary-menu &optional (superior tvrmouse-sheetj Resource 

A resource of momentary menus, tvrmenu-choose allocates a window from this re- 
source. 



tv:momentary-menu Flavor 

Built on tv:basic-momentary-menu mixed with tvrmenu. See the section "The 
Flavor Network of tvrmenu". 

Momentary menus display a list of items. The user can avoid making a choice by 
moving the mouse outside the menu. In this case, the menu disappears. 



tv:momentary-multiple-item-list-menu Flavor 

The instantiable version of the multiple-item-list-menu flavor. It is a mixture of 
tv:multiple-item-list-menu-mixin with tv:basic-momentary-menu and other appro- 
priate flavors. 



tv:momentary-multiple-menu Flavor 

Built on tv:multiple-menu-mixin and tvrmenu-highlighting-mixin with 
tv:momentary-menu. 

The menu is exposed near the mouse, and like any momentary menu, the menu 
disappears once the user has made a choice. 



tv:momentary-window-hacking-menu Flavor 

A momentary menu combined with tv:window-hacking-menu-mixin. The window 
that the menu is exposed over is remembered when the rchoose message is sent. 
The remembered window is used if a :window-op type item is selected. 



timermonth-length month year Function 

Returns the number of days in month; you must supply a year in case the month 
is February (which has a different length during leap years), year can be absolute 
or relative to 1900 (that is, 84 and 1984 both work). 



timermonth-string month &optional (mode ':long) Function 

Returns a string representing the month of the year. As usual, 1 means January, 2 
means February, and so on. Possible values of mode are: 

rshort Return a three-letter abbreviation, such as "jan", "feb", and so on. 

:long Return the full English name, such as "January", "february", and so 

on. This is the default. 
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rmedium Same as rshort, but use "sept", "novem", and "decern". 

rfrench Return the French name, such as "Janvier", "fevrier", and so on. 

rroman Return the Roman numeral for month (this convention is used in Eu- 
rope). 

rgerman Return the German name, such as "januar", "februar", and so on. 

ritalian Return the Italian name, such as "gennaio", "febbraio", and so on. 



(flavorrmethod :more-p tvrsheet) t-or-nil Init Option 

Initializes whether the window should have more processing. It defaults to t. 

(flavorrmethod :more-p tvrsheet) Method 

Returns t if more processing is enabled; otherwise, return nil. 

tvrmouse-button-encode bd Function 

Watches the mouse button and determines whether a single-click or double-click is 
happening. Call this function when a mouse button has been pushed and you want 
to interpret the push as a click. It returns nil if no button is pushed, or an encod- 
ed integer giving the click in the usual way. 

You call tvrmouse-button-encode only when a button has just been pushed; that 
is, when you see some button down that was not down before. You must pass in 
the argument, bd, which is a bit mask saying which buttons are down now that 
were not down "before". The form (boole 2 old-buttons new-buttons) computes this 
mask. 

sysrmouse-buttons &optional peek Function 

Returns the current state of the mouse buttons. If peek is not nil, it looks at the 
state without pulling anything out of the buffer (of pending mouse-button transi- 
tions). 

It returns four values: 

• An integer representing the state of the mouse buttons. means no buttons 
were pressed; 1, 2, and 4 represent the Left, Middle, and Right buttons, respec- 
tively. (Except on the Symbolics 3600, chording is not supported; that is, if more 
than one button is pressed, the integer returned is not the sum of the individual 
button codes.) 

• An integer representing the time when that state was true. 

• The X-coordinate of the mouse at that time. 
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• The Y-coordinate of the mouse at that time. 

To use some parts of the mouse software, such as tvrmouse-button-encode, you 
can store these four returned values into the variables tv:mouse-last-buttons, 
tv:mouse-last-buttons-time, tv:mouse-last-buttons-x, and tv:mouse-last-buttons-y, 

respectively. The mouse process does this itself when the mouse is not usurped. 



mouse-char-p char Function 

Returns t if char is a mouse character, nil otherwise. 

(flavorrmethod :mouse-click tv:essential-mouse) buttons x y Method 

Called by the rmouse-buttons method of tv:essential-mouse, which is called by 
the default mouse handler when mouse buttons are pushed, buttons is a structure 
representing the buttons pushed; use reader macros like #\Mouse-R to handle 
these structures in your program. (See the section "Mouse Characters".) x and y 
represent the position of the mouse at the time of the click, in the window's out- 
side coordinates. 

If the click is #\sh-Mouse-R, the rmouse-buttons method pops up a system menu. 
Otherwise, if the window has an I/O buffer, rmouse-click sends it a blip of the 
form (rmouse-button buttons window x y). In addition, if the click is #\Mouse-L, 
the window is selected. 

rmouse-click methods are combined using ror combination, so the rmouse-click 
method of tvressential-mouse runs only if no earlier method handles the message 
(and all earlier methods return nil). This allows a method to intercept only certain 
clicks and return non-nil, and to pass on other clicks and return nil. 

tvrmouse-double-click-time Variable 

The maximum period of time (in microseconds) between mouse clicks for which 
the clicks are interpreted as a double click instead of two single clicks. Default: 
200000 (decimal). If you set this to nil, disabling double clicking entirely, mouse 
response time improves slightly in static windows and appreciably in Dynamic 
Windows. This is the recommended setting. 

tvr *mouse-incrementing-key states* Variable 

A list of names of keys, acceptable to tvrkey-state. If one or more of these keys 
are pressed, single mouse clicks are interpreted as double clicks. Default: (rshift). 

tvrmouse-input &optional (wait-flag t) Function 

Waits until something happens with the mouse, then returns saying what hap- 
pened. It returns six values. The first two are delta-x and delta-y, which are the 
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distance that the mouse has moved since the last time tv:mouse-input was called. 
The second two are buttons-newly-pushed and buttons-newly-raised, which are bit 
masks (using the bit assignment used by tv:mouse-last-buttons) saying what but- 
tons have changed since the last time tv:mouse-input was called. The last two 
values are the current x- and y-position of the mouse or, if any buttons changed, 
the position of the mouse at that time. 

You can call this function only with the mouse usurped; otherwise you will get in 
the way of the mouse process, which calls it itself, and mouse tracking will not 
work correctly. 

The variables sys:mouse-x and sys:mouse-y are not maintained by this function; 
you must do it yourself if you want to keep track of a cumulative mouse position. 
tv:mouse-last-buttons is maintained. 

The buttons-newly-pushed value is suitable for being passed as an argument to 
tvrmouse-buttons-encode, which can be used with the mouse usurped as well as 
with the mouse grabbed. 

If wait-flag is nil, then the function does not wait; it can return with all zeroes, 
indicating that nothing has changed. 



tv:mouse-last-buttons Variable 

Contains the last setting of the mouse buttons noticed by the process handling the 
mouse, which is normally the mouse process. The numbers 1, 2, and 4 represent 
the Left, Middle, and Right buttons, respectively. (Except on the Symbolics 3600, 
chording is not supported; that is, if more than one button is pressed, the integer 
returned is not the sum of the individual button codes.) 



tv: *mouse-modif ying-key states* Variable 

A list of names of keys acceptable to tv:key-state. If one or more of these keys 
are pressed, sets the corresponding modifier bits in the mouse character. Default: 
(rcontrol :meta rsuper rhyper). If a key appears as an element of both this list 
and the list that is the value of tv:*mouse-incrementing-key states*, the modifier 
bit is set and the click is interpreted as a double click. 



(flavorrmethod :mouse-moves tv:essential-mouse) x y Method 

The default mouse handler sends this message to the window when the mouse has 
moved or buttons have been pushed, x and y represent the current position of the 
mouse if it has moved or its position at the time of the click if buttons have been 
pushed. The arguments are in the window's outside coordinate system. The method 
tracks the mouse blinker. 



dw:mouse-char-for-gesture gesture Function 
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Returns the mouse character associated with a gesture. You can use this function 
to assign a new gesture symbol to a mouse character. 

gesture An existing or new gesture symbol. 

To assign your own symbolic name to a mouse character, use the following form: 

(setf (mouse-char-for-gesture gesture) #\mouse-x) 

Conventionally, the gesture symbol is a keyword. 

For an overview of dw:mouse-char-for-gesture and related facilities: See the sec- 
tion "Mouse Gesture Interface Facilities". 

For information on mouse characters: See the section "Mouse Characters". 

dw:mouse-char-gesture mouse-char Function 

Returns the standard gesture associated with a mouse character. 

mouse-char The mouse character (for example, #\mouse-m). 

For an overview of dw:mouse-char-gesture and related facilities: See the section 
"Mouse Gesture Interface Facilities". 

For information on mouse characters: See the section "Mouse Characters". 

dw:mouse-char-gestures mouse-char Function 

Returns a list of gestures associated with a mouse character. 

mouse-char The mouse character (for example, #\mouse-m). 

For an overview of dw:mouse-char-gestures and related facilities: See the section 
"Mouse Gesture Interface Facilities". 

For information on mouse characters: See the section "Mouse Characters". 

rmouse-select &optional (save-selected t) Message 

When sent to a window selects the window, as a result of a user command, usually 
clicking the mouse on it. This takes care of various window system issues, such as 
making sure that typeahead goes to the correct activity and getting rid of any 
temporary windows that are covering this window, preventing it from being ex- 
posed. 

The operation fails and returns nil if this window is not contained inside its supe- 
rior (it might be too large), which prevents it from being exposed. The operation 
can also fail and return nil if the message is sent to a frame whose selected-pane 
is nil. If the operation succeeds, the message returns t. 
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If save-selected is not nil, the previously selected activity is saved for restoring by 
the FUNCTION S command and the rdeselect message. 

The rmouse-select message to a pane (a window with tv:pane-mixin) selects the 
activity of which the pane is a part, without changing its selected-pane. Thus, the 
message does not necessarily select the window to which it is sent; it might select 
some other window in the same activity, rmouse-select is intended to be a com- 
mand for switching activities. 

User programs should send the : select-relative message rather than rselect or 
rmouse-select, unless they are really responding to a user command to switch ac- 
tivities. Using : select-relative rather than rmouse-select or rselect to change win- 
dows within an activity ensures that the right thing happens when that activity is 
not the selected one and avoids suddenly changing the selected activity without the 
consent of the user. 

This message is sent by many parts of the user interface. 

This message is usually received by the system, although users could define meth- 
ods for it: either a method that returns nil to prevent a window from being select- 
ed, or a daemon. The default method is defined on tvressential-window. 



(flavorrmethod rmouse-sensitive-item tvrmouse-sensitive-text-scroll-window- 
without-click) x y Method 

Returns the mouse-sensitive item at a given location. 

The arguments are the x and y coordinates of the location. Two values are re- 
turned: the item and its type, or nil and nil if the mouse was not over any mouse- 
sensitive item. 

This message is useful to send from your rmouse-click handler; the x and y pa- 
rameters from rmouse-click can be passed along. 



tvrmouse-sensitive-text-scroll-window Flavor 

To use this flavor, you must create your own flavor based on this one, and rede- 
fine the rprint-item message. Your new handler for rprint-item can send the ritem 
message to the window to create a new mouse-sensitive item. 



tvrmouse-sensitive-text-scroll-window-without-click Flavor 

Like tvrmouse-sensitive-text-scroll-window, but without the rmouse-click method, 
so that you can provide your own. (You can't just override it, because rmouse-click 
is combined with the ror) method combination. 



tvrmouse-set-blinker-cursorpos Function 

Positions the mouse blinker at point (sysrmouse-x, sysrmouse-y) on tvrmouse- 
sheet. 
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tv:mouse-sheet Variable 

The value is the superior window, usually the main screen, that contains the posi- 
tion of the mouse. 



tv:mouse-wait &optional (old-x sys:mouse-x) (old-y sys:mouse-y) (old-buttons 
tv:mouse-last-buttons) (whostate "Mouse") (timeout nil) Function 

Waits until any of the variables sys:mouse-x, sys:mouse-y, or tv:mouse-last- 

buttons becomes different from the values passed as arguments, or until timeout 
sixtieths of a second have elapsed. While waiting, whostate is displayed in the sta- 
tus line. To avoid timing errors, your program should examine the values of the 
variables, use them, and then pass in the values that it examined as arguments to 
tv:mouse-wait when it is done using the values and wants to wait for them to 
change again. It is important to do things in this order, or else your program 
might fail to wake up if one of the variables changed while you were using the old 
values and before you called tv:mouse-wait. 

tv:mouse-wait returns three values: 

• An integer representing the state of the mouse buttons, in the format used by 
the variable tv:mouse-last-buttons. 

• The X-coordinate of the mouse. 

• The Y-coordinate of the mouse. 



sysrmouse-wakeup Function 

Causes tv:mouse-input to return as if the mouse had moved. This causes the de- 
fault mouse handler to send the window owning the mouse a :mouse-moves mes- 
sage. 



tv:mouse-warp x y &optional (mouse tvrniain-mouse) Function 

Positions the mouse blinker at screen coordinates x and y. (The optional argument 
mouse is used in multiple-console systems.) 

To position the mouse blinker at coordinates relative to a particular window, use 
(flavorrmethod : set-mouse-position tv:essential-mouse). 



sys:mouse-x Variable 

The value is the x-coordinate of the position of the mouse, in pixels, measured 
from the upper-left corner of the screen the mouse is on (the value of tvrmouse- 
sheet). This variable is maintained by the process handling the mouse, normally 
the mouse process. It is in outside coordinates, since the mouse might be in the 
margins somewhere. 
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tv:mouse-x-scale-array Variable 

The value is an array that, along with the array that is the value of tv:mouse-y- 
scale-array, can be used to control mouse scaling. These arrays determine the re- 
lation between the rates of motion of the mouse on the table and the mouse cursor 
on the screen. This relation can be nonlinear and can vary with the speed of the 
mouse. For example, fast mouse motion can move the cursor a distance that is 
proportionally greater than slow mouse motion. 

Scaling is computed as follows. The even-numbered elements of tv:mouse-x-scale- 
array are compared with the value of tv:mouse-x-speed, and the even-numbered 
elements of tv:mouse-y-scale-array are compared with the value of tv:mouse-y- 
speed. tv:mouse-x-speed and tv:mouse-y-speed are the x- and y-components of the 
mouse speed on the table, typically in units of hundredths of an inch per second. 

For each array, the first even array element that is greater than the mouse speed 
causes its corresponding odd-numbered array element to be multiplied by the 
mouse motion on the table and then divided by 1024 (decimal). The result is the 
mouse motion on the screen. Appropriate care is taken to save the fractions for 
the next computation. 

The default array setup code is as follows: 

;;; Use a scale of 2/3 in X, 3/5 in Y when moving at slow speed, 

;;; double that at high speed 

(aset 80. tv:mouse-x-scal e-array 0) 

(aset (// (lsh 2 10.) 3) tv:mouse-x-scal e-array 1) 

(aset 80. tv:mouse-y-scal e-array 0) 

(aset (// (lsh 3 10.) 5) tv:mouse-y-scal e-array 1) 

(aset #017777777777 tv:mouse-x-scal e-array 2) 

(aset (// (lsh 4 10.) 3) tv:mouse-x-scal e-array 3) 

(aset #017777777777 tv:mouse-y-scal e-array 2) 

(aset (// (lsh 6 10.) 5) tv:mouse-y-scal e-array 3)) 

The following code provides for simple scaling of motion for the Hawley mouse. 
The arrays are specially wired. You can store into each array, but you cannot re- 
place it with a new array or use zl:adjust-array-size on it. 

Aids to trying speed-dependent scaling 
Specs are scale-factor speed-break 
No attempt to treat X and Y differently 

Args of (1 80. 2) seem to be about right for the Hawley mouse 
(defun mouse-speed-hack (&rest specs) 

(loop for (scale speed) on specs by 'cddr 
for i from by 2 

do (aset (or speed #037777777) tv:mouse-x-scal e-array i) 
(aset (or speed #037777777) tv:mouse-y-scal e-array i) 
(aset (// (fix (* 2 scale 1024.)) 3) 
tv:mouse-x-scal e-array (1+ i)) 
(aset (// (fix (* 3 scale 1024.)) 5) 

tv:mouse-y-scal e-array (1+ i)))) 
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(defun hawley-mouse-hack () 
(mouse-speed-hack 1 80. 2)) 



sys:mouse-y Variable 

The value is the y-coordinate of the position of the mouse, in pixels, measured 
from the upper-left corner of the screen the mouse is on (the value of tvrmouse- 
sheet). This variable is maintained by the process handling the mouse, normally 
the mouse process. It is in outside coordinates, since the mouse might be in the 
margins somewhere. 



tv:mouse-y-or-n-p item Function 

Takes an item as its argument and displays it in a menu, item is usually a string. 
If the user clicks on "Yes" with the mouse button, the value of the item is re- 
turned. If the user clicks on "No" with the mouse or moves the mouse out of the 
menu, nil is returned. 



tv:mouse-y-scale-array Variable 

The value is an array that, along with the array that is the value of tv:mouse-x- 
scale-array, can be used to control mouse scaling. 

See the variable tv:mouse-x-scale-array. 



tvrmultiple-choice Flavor 

An instantiable window flavor with the multiple-choice facility in it. It has borders 
and a label area on top which is used for the column headings. 



tvrmultiple-choose item-name item-list keyword-alist &optional (near-mode 
'(:mouse)J (maxlines 20) sup (blinker-style '(nil :bold nil)) Function 

Pops up a multiple-choice window and allows the user to make choices with the 
mouse. Unless you specifiy otherwise, the dimensions of the window are automati- 
cally chosen for the best presentation of the specified choices. If there are too 
many choices, scrolling of the window is enabled. 

See the section "The Multiple Choice Facility", item-name is a string of the name 
of the type of item, for example, /"Buffer/". 

item-list is an alist, (item name choices), item is the item itself, name a string of 
its name, and choices a list of possible keywords, either keyword or (keyword de- 
fault), where if default is non-nil the keyword is initially on. 

keyword-alist is a list of the possible keywords, (keyword name . implications), key- 
word is a symbol, the same as in item-list's choices, name is a string of its name. 
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implications is a list of on-positive, on-negative, off-positive, and off-negative impli- 
cations for when the keyword is selected, each one either a list of (other) keywords 
or t for all other keywords. The default for implications is (nil t nil nil). 

The finishing-choices, [Do It] and [Abort], are prespecified by the system and can- 
not be changed by the user. 

When the user clicks on one of the two finishing choices in the bottom margin 
([Do It] and [Abort]), the window disappears and tvrmultiple-choose returns. Two 
cases obtain: 

• If the user finishes by choosing [Abort] the returned value is nil. 

• If the user chooses [Do It], the returned value is a list with one element for 
each item. Each element is a list whose car is the item (that arbitrary object 
which the user passed in the item-list argument) and whose cdr is a list of the 
keywords for the "yes" choices selected for that item. 

near-mode tells the window where to pop up. It is a suitable argument for 
tv:expose-window-near. The default is the list (rmouse). 

maxlines, which defaults to twenty, is the maximum number of choices allowed be- 
fore scrolling is used. 

sup is the superior of the menu. By default, this is the sheet superior of the win- 
dow that the mouse is near, if the near-mode is :window; otherwise, it is the 
mouse-sheet. 

blinker-style is a character style specification that indicates how selected items in 
the menu are to be highlighted. The default is '(nil :bold nil). 



tv:multiple-menu Flavor 

A combination of tv:multiple-menu-mixin with tvrmenu. It must be explicitly de- 
activated by the user program. 



tv:multiple-menu-choose item-list defaults &optional near-mode Function 

item-list is a list of lists of menu items. Each sublist corresponds to a column, de- 
faults is a list of menu items, one for each column, which are initially highlighted. 

The function pops up a menu and allows the user to make choices with the mouse. 
The special choices [Do It] and [Abort] are supplied automatically. The function re- 
turns the list of selected menu items or nil if the user aborts. Note: The 
tv:multiple-menu-choose function executes items when they are chosen, not when 
the [Do It] choice is made. The menu items should not have any side-effects when 
executing. For an example, See the section "tv:multiple-menu-choose Example". 



tv:multiple-menu-choose-menu Flavor 
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The instantiable version of the multiple-menu-choose flavor, constructed by mixing 
tv:multiple-menu-choose-menu-mixin with tvrmenu. It accepts the rmultiple- 
choose message. 



tv:multiple-menu-choose-menu-mixin Flavor 

The basic flavor that makes a window exhibit multiple-menu-choose behavior. 

tv:multiple-menu-mixin Flavor 

Gives a menu the ability to have multiple items "selected". Selected items are 
highlighted with inverse video, using the tv:menu-highlighting-mixin. Clicking on 
an item merely complements its selected state and does not execute it or return 
from the rchoose message. 

Normally, at the top of the menu, in italics, are displayed some "special choices" 
(for example, [Do It] or [Abort]) that cannot be highlighted. Clicking on one of 
these behaves the same as clicking on an item of an ordinary menu. 

By default, the only special choice is [Do It], which returns (from the rchoose 
message) a list of the results of executing all the highlighted choices (that is, the 
result of the rhighlighted-values message). You can define your own special choic- 
es with the : special-choices init-plist option, or get rid of them entirely by giving 
nil as the argument to this option. 

(flavorrmethod rname tvrmenu) string Init Option 

Names the window. The name appears in such places as the list of windows gener- 
ated by [Select] in the System menu and in the window display option of Peek. 
The name is the default string for the label if another label string is not specified. 

(flavorrmethod rname tvrsheet) Method 

Returns the name of the window, which is a string. 

(flavorrmethod rname tvrsheet) name Init Option 

The value is the name of the window, which should be a string. All windows have 
names; note that this is an init option of tvrsheet. It is mentioned here because 
the main use of the name is as the default string for the label, if there is a label. 

mame-for-selection Message 

Returns nil if the window is not supposed to be selected. Otherwise, it returns a 
string that serves as the name of the window in menus of selectable windows. 

This message is sent by many parts of the user interface. Some use it just as a 
predicate; others put the returned string into a menu. 



Page 1323 



This message is usually received by the user. The default method (of tvrsheet) re- 
turns nil. tv:select-mixin provides a method that computes a name based on the 
window's label, if it has one, or else on the window's name. 

Many application programs shadow this method and supply their own. This is espe- 
cially so in the case of program frames. Typically, you do not want pane names to 
show up in select menus. The recommended procedure for addressing this issue is: 

1. Make your frame's panes include tv:pane-no-mouse-select-mixin instead of 
tv:pane-mixin if you do not want them showing up in menus. 

2. Give your frame a name that you do want to show up in menus. 

3. If you want the name to be something separate, or if you have some panes 
that are menu-selectable for some reason, provide your own :name-for- 
selection method for the frame. 



(flavorrmethod :name-style tvrbasic-choose-variable-values) character-style 

Init Option 

Specifies the character style in which names of variables are displayed. The de- 
fault is the system default character style. 



dw:named-value-snapshot-continuation name var-list &body body Function 

Generates a lexical closure of its body, except that it snapshots the current values 
of lexical variables used free within body. 

name The internal-function name for the generated lexical closure. This 
supplies the X in names like (: INTERNAL SOMETHING 2 X). 

var-list The lambda-list for the generated lexical closure. 

dw:named-value-snapshot-continuation can be of use, for example, when collect- 
ing closures within an iteration. The following code 

(defun print-reverse-of-1 ist (list) 
(let ((1 ist-of-closures ())) 
(dolist (x list) 

(push (lambda (stream) (print x stream)) 
1 ist-of-closures)) 
(dolist (closure 1 ist-of-closures) 

(funcall closure xstandard-outputx)))) 

(print-reverse-of-1 ist '(1 2 3)) 

would print three occurrences of 3. This is because the first dolist might 
macroexpand into something like 
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(let ((x) (temp list)) 
(prog nil 

loop (when (null temp) (return)) 
(setq x (pop temp)) 
(push (lambda (stream) (print x stream)) 

1 ist-of-closures) 
(go loop))) 

where all the (lambda . . .) share exactly the same binding of x. Unfortunately, this 
means that each time through the loop, x — the same x in all the closures — gets 
setq'd. A way around this is to introduce a new binding for the x at the point the 
closure is produced: 

(let ((x) 

(temp list)) 
(prog nil 

(when (null temp) (return)) 
(setq x (pop temp)) 
(push (let ((x x)) 

(lambda (stream) (print x stream))) 
1 ist-of-closures))) 

Here the x snapshotted by the closure is different for each closure, achieving the 
desired effect. 

dw:named-value-snapshot-continuation processes the body, identifying freely- 
referenced lexical variables which need such snapshotting. It also does special pro- 
cessing for self and instance variables referenced within flavor methods. As a re- 
sult, the above fragment could be written 

(defun print-reverse-of-1 ist (list) 
(let ((1 ist-of-closures ())) 
(dolist (x list) 

(push (dw : named-val ue-snapshot-conti nuati on 
writer (stream) 
(print x stream)) 
1 ist-of-closures)) 
(dolist (closure 1 ist-of-closures) 

(funcall closure xstandard-outputx)))) 

and then (print-reverse-of-1 ist '(1 2 3)) would correctly print 3, 2, 1. 

For an overview of dw:named-value-snapshot-continuation and related facilities: 
See the section "Writing Formatted Output Macros". See the section "Snapshotting 
Variables". 



(flavorrmethod :near-mode tvrchoose-variable-values) arg Init Option 
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Specifies where to position the window. The default is the list (rmouse). See the 
section "Input from Windows". 



:no-input-save Option 

The input editor does not save the scanned contents of the input buffer on the in- 
put history when returning from the reading function. This is intended for use by 
functions such as fquery that use the input editor to ask simple questions whose 
responses are not worth saving. zl:yes-or-no-p uses :no-input-save by default. 



tv:no-screen-managing-mixin Flavor 

Prevents the screen manager from dealing with the inferiors of a window. 

tv:*no-window-alternate-wholine-string* Variable 

Controls what appears in the status line when switching windows. A program can 
set tv:*no-window-alternate-wholine-string* to indicate what is happening. The 
default string is (no window). 



(flavorrmethod :noise-string-out sirinteractive-stream) string &optional (rescan- 
mode rignore) Method 

Can be sent by a read function to display a string that is not to be treated as in- 
put. For example, the string might prompt the user for a particular kind of input. 
string is displayed on the screen without changing the scan pointer, and a rescan 
does not take place. If a rescan takes place at some later time, the characters in 
string are ignored. 

rescan-mode specifies what action to take if the :noise-string-out message is sent 
when the scan pointer is not at the end of the input buffer: 

rignore Do not perform the :noise-string-out operation. This is the de- 

fault. 

renable Perform the operation. 

rerror Signal an error. 



:notification-cell Message 

Sent to an interactive stream, it returns the locative in which the notification de- 
livery process stores notifications. If some process notifies the user, the notifica- 
tion delivery process gives the process associated with the selected window a 
chance to accept the notification. It does this by trying to store the notification in 
the locative returned by the :notification-cell message to the selected window, un- 
less the locative contains a notification already. In that case the notification deliv- 
ery process usually tries to display the notification itself. 
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A user process that wants to accept notifications should find this locative by send- 
ing the :notification-cell message to the selected window. It should wait (usually 
in an :input-wait wait function) for the locative to contain something other than 
nil. The user process can receive the notification by sending the selected window a 
rreceive-notification message. 



tv:*notification-deliver-timeout* Variable 

The length of time, in sixtieths of a second, that the notification delivery process 
waits for the process associated with the selected window to accept a notification. 
If the selected window's process does not accept the notification during this time, 
the delivery process takes the notification back and usually tries to display it it- 
self. Default: 180. (three seconds). 



rnotification-handler function &rest arguments Option 

If a notification is received while in the input editor, function is called to handle 
it. function should take at least one argument, the notification (as returned by the 
rreceive-notification message to the stream), arguments are the remaining argu- 
ments to function, function can do anything it wants with the notification. To dis- 
play the notification, function would usually call sysrdisplay-notification. 

If this option is not specified, notifications appear one after the other using 
rinsert-style typeout. 

Following are two simple examples of notification handlers. The first handler as- 
sumes that you want each notification to overwrite the previous one. The second 
handler assumes that you want them to appear one after another. *window* 
should be bound to a window and *stream* to a stream where you want the notifi- 
cations to appear. 

(defun my-notif ication-handler-1 (notification) 
(send xwindowx : clear-window) 
(sys:display-notif ication xwindowx notification :window)) 

(defun my-notif ication-handler-2 (notification) 

(sys:display-notif ication xstreamx notification :stream)) 



:notification-mode Message 

Sent to an interactive stream, it returns the stream's notification mode. The notifi- 
cation mode determines what the notification delivery process does with a notifica- 
tion when the process associated with the stream does not accept it: 

:pop-up The notification is displayed in a pop-up window. This is the 

default. 

rblast The notification is displayed on the stream. 
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rignore The notification is ignored but is added to the notification his- 

tory for SELECT N and the Show Notifications command. 



nil The same as :pop-up. 



tv:*notification-pop-down-delay* Variable 

The amount of time, in sixtieths of a second, that a notification pop-up window re- 
mains exposed if the user types no characters to the window. A value of nil means 
that the window remains exposed indefinitely. Default: 54000. (15 minutes). 



tvmotify window-of-interest format-control &rest format-args Function 

Issues an asynchronous notification to the user. Constructs a notification and push- 
es it onto a queue. A central notification delivery process delivers the notification 
to the user. The text of the notification is constructed from format-control and for- 
mat-args. If window-of-interest is not nil, it is a window to be made available via 

FUNCTION S. 



(flavormiethod :number-of-items tvrtext-scroll-window) Method 

Returns the number of items in the item list. 



tvmote-progress numerator &optional (denominator 1) (note tv:*current-progress- 
note*) Function 

Notes the progress of an operation by updating the progress bar. This function is 
only used in the body of the tvmoting-progress macro (for examples, look at the 
dictionary entry for that facility). The progress bar is updated by fractional 
amounts between and 1. 

numeratorThe numerator of the fraction by which to update the bar. 

denominator The denominator of the fraction by which to update 

the bar; the default is 1. 

note The note object (bound to the variable supplied to tvmoting- 

progress). 

For an overview of tvmote-progress and related facilities, see the section 
"Progress Indicator Facilities". 



tvmoting-progress (name &optional (variable 'tv:*current-progress-note*) (process 
'sysrcurrent-process)) &body body Function 

Binds local environment such that the progress of an operation performed within 
the body of the macro is noted by a progress bar displayed in the status line at 
the bottom of the screen. The function tvmote-progress does the updating of the 
progress bar. 
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name A string naming the operation being noted. This string is displayed 
above the progress bar. 

variable The variable bound to the note object; the default is tv:*current- 
progress-note*. This variable is an argument to tvrnote-progress. 

process The process on whose behalf the progress is noted; the default is 
sysrcurrent-process. This is used to determine the precedence of 
notes. 

Examples: 

(tv:noting-progress ("Working Away By Tenths") 
(loop for i from .1 to 1.0 by .1 
do 
(tv: note-progress i) 
(sleep 1))) 

(tv:noting-progress ("Working Away By Fifths") 
(loop for i from 1 to 2 by 1 
do 
(sleep 1)) 
(tv: note-progress 1 5) 
(loop for i from 1 to 2 by 1 
do 
(sleep 1)) 
(tv: note-progress 2 5) 
(loop for i from 1 to 2 by 1 
do 
(sleep 1)) 
(tv: note-progress 3 5) 
(loop for i from 1 to 2 by 1 
do 
(sleep 1)) 
(tv: note-progress 4 5) 
(loop for i from 1 to 2 by 1 
do 
(sleep 1)) 
(tv: note-progress 5 5) 
(sleep 1)) 

For an overview of tvrnoting-progress and related facilities, see the section 
"Progress Indicator Facilities". 



tv:pane-mixin 



Flavor 



Must be one of the components of the flavor of any window used as a pane of a 
frame. For example, the flavor tv:window-pane, used when you want a pane of a 
frame that understands everything that tvrwindow does, is defined as follows: 
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(defflavor tv: window-pane () (tv: pane-mi xin tv:window)) 

Among other things, tv:pane-mixin provides methods that let the pane participate 
in its superior's activity. The :alias-for-selected-windows method returns the su- 
perior's alias. When a window of this flavor receives a rselect message, it first 
sends its superior an rinferior-select message. If the rinferior-select message re- 
turns nil, the rselect message fails and just returns nil. When a window of this 
flavor receives a rmouse-select message, it passes the message on to its superior. 



(flavorrmethod :pane-name tvrbasic-constraint-frame) pane Method 

Returns the symbol that was used to name pane in the rpanes specification of this 
frame. If pane is not one of the panes, return nil. 



tv:pane-no-mouse-select-mixin Flavor 

Makes a window a pane of a frame and ensure that it cannot be selected from a 
system menu. This flavor includes tv:pane-mixin and tvrdont-select-with-mouse- 
mixin. 



(flavorrmethod rpanes tvrbasic-constraint-frame) pane-descriptions Init Option 

Required for all flavors of constraint frames. The argument, pane-descriptions, is a 
list of pane descriptions. Every pane description looks like this: 

(name flavor . options) 

name is the internal name (a symbol), flavor is the flavor of which the pane should 
be an instance, options is a list to be appended to the initialization plist for the 
pane when it is created. When the frame is first created, it will create all of its 
panes, using the flavor and options. The frame will add some of its own options to 
control the position and shape of the window; you should not pass any such options 
in the options list. 



timerparse string &optional (start 0) end (futurep t) base-time must-have-time date- 
must-have-year time-must-have-second (day-must-be-valid t) Function 

Interprets string as a date and/or time, and return seconds, minutes, hours, date, 
month, year, day-of-the-week, daylight-savings-time-p, and relative-p. start and end 
delimit a substring of the string; if end is nil, the end of the string is used, must- 
have-time means that string must not be empty, date-must-have-year means that a 
year must be explicitly specified, time-must-have-second means that the second 
must be specified, day-must-be-valid means that if a day of the week is given, it 
must actually be the day that corresponds to the date, base-time provides the de- 
faults for unspecified components; if it is nil, the current time is used, futurep 
means that the time should be interpreted as being in the future; for example, if 
the base time is 5:00 and the string refers to the time 3:00, that means the next 
day if futurep is non-nil, but it means two hours ago if futurep is nil. The 
relative-p returned value is t if the string included a relative part, such as "one 
minute after" or "two days before" or "tomorrow" or "now"; otherwise, it is nil. 
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si:parse-interval-or-never string Function 

Returns an integer if string represents an interval, or nil if string represents 
"never", string is the character- string representation of an interval of time, start 
and end specify a substring of string to be parsed; they default to the beginning 
and end of string, respectively. If string is anything else, an error occurs. Examples 
of acceptable strings: 

"4 seconds" "4 sees" "4 s" 

"5 mins 23 sees" "5 m 23 s" "23 SECONDS 5 M" 

"never" "not ever" "no" 

"3 yrs 1 week 1 hr 2 rains 1 sec" 

Note that several abbreviations are understood, the components can be in any or- 
der, and case (upper versus lower) is ignored. Also, "months" is not acceptable, 
since months vary in length. This function accepts anything that timerprint- 
interval-or-never produces, and it returns the same integer (or nil). 



See the presentation type timertime-interval. 



time:parse-present-based-universal-time time-being-parsed Function 

Like time:parse-universal-time, except that missing components in time-being- 
parsed are defaulted to the beginning of the smallest unsupplied unit of time. The 
returned values are the same as those of time:parse-universal-time. time-being- 
parsed is a string suitable as the first argument to time:parse-universal-time. 

For example, "5 pm" is parsed as 5 pm on the current day, whether the current 
time is before or after 5 pm. "Thursday" is parsed as Thursday of the current 
week, whether today is Wednesday or Friday. "1 June" is parsed as June 1 of the 
current year, whether the date is before or after June 1. 



time:parse-universal-time string &optional (start 0) end (futurep t) base-time must- 
have-time date-must-have-year time-must-have-second (day-must-be-valid t) Function 

The same as timerparse except that it returns one integer, representing the time 
in Universal Time, and the relative-p value. It also returns a third value, which is 
t if hours, minutes, or seconds were specified by string, or nil if they were not. 



time:parse-universal-time-relative date-spec reference-date-spec &optional (future-p 
t) Function 

Like time:parse-universal-time, except that date-spec is parsed relative to refer- 
ence-date-spec. The returned values are the same as those of timerparse-universal- 
time. 

date-spec is a string suitable as the first argument to time:parse-universal-time. 
reference-date-spec is a universal-time integer or a string that can be parsed as an 
unambiguous time. If future-p is nil, an ambiguous date-spec is interpreted as be- 
ing in the past relative to reference-date-spec; otherwise, it is interpreted as being 
in the future. The default for future-p is t. 
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For example: 

(time: parse-universal -time-relative "5 pm" "today") 

returns the same value when evaluated anytime today, whether or not the current 
time is before or after 5 pm. 

:partial-help &rest help-option Option 

When the user presses HELP, the input editor first types out a message determined 
by help-option. It then types out a message describing how to invoke input editor 
commands and other information about the stream. If a :brief-help, 
:complete-help, or :merged-help option has been specified, it overrides rpartial- 
help. 

help-option can have one element, which can be a string, a function, or a symbol; 
or it can have more than one element. For an explanation: See the section "Dis- 
playing Help Messages in the Input Editor". 

This option is intended for use when inexperienced users might be typing to the 
input editor. Often help-option gives some information about the program to which 
the user is typing and what the user can do to exit from it. 

:pass-through &rest characters Option 

The characters in characters are not to be treated as special by the input editor. 
This option is used to pass format effectors (such as HELP or CLERR INPUT) 
through to the reading function instead of interpreting them as input editor com- 
mands. :pass-through is allowed only for characters with no modifier bits set, that 
is, for character codes through 377 (octal). For characters that have modifier 
bits set and must be visible to the reading function, use :do-not-echo or 
: activation. 

peek-char &optional peek-type input-stream (eof-error-p t) eof-value recursive-p 

Function 

Returns the next character to be read from input-stream, without actually remov- 
ing it from the stream. (This is the default behavior, which can be modified by the 
peek-type argument.) 

What peek-char does depends on peek-type. The effects of peek-type are as follows: 

Value Effect 

nil Returns the next character to be read from input-stream, with- 

out actually removing it from the stream. The next time input 
is done from input-stream, the character will still be there. It 
is as if you had called read-char, then unread-char in succes- 
sion. 
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t Skips over whitespace characters (but not comments), and then 

performs the peeking operation on the next character. This is 
useful for finding the beginning of the next printed representa- 
tion of a Lisp object. The last character examined (the one 
that starts an object) is not removed from the input stream. 

character object Skips over input characters until a character that is char= to 
that object is found. That character is left in the input stream. 

A value of t for input-stream indicates *terminal-io*. If input-stream is unspecified 
or nil, then *standard-input* is used. 

The arguments eof-error-p and eof-value control what happens when the function is 
called at the end of input-source. If the first argument, eof-error-p is nil, then 
nothing is done, otherwise an end-of-file error is signalled, and the value returned 
is eof-value. 

The recursive-p argument is used to signal that the call to peek-char is not at the 
top level. 

(list (read-char) (peek-char) (read-char) (read))abcdef 
=> (#\a #\b #\b CDEF) 

(list (read-char) (peek-char) (read))abcdef 
=> (#\a #\b #\b BCDEF) 

For a discussion of keyboard input differences between CLOE and Genera, see the 
function read-char. 



dw:peek-char-for-accept stream &optional hang Function 

Returns the next character in the input stream without removing it from the 
stream. This is equivalent to calling dw:read-char-for-accept followed by 
dw:unread-char-for-accept. 

stream The input stream. 

hang Boolean option specifying whether, if no character is available in 
the input stream, the function waits until a character is available 
or returns nil. The default is nil. 

For an overview of dw:peek-char-for-accept and related facilities, see the section 
"Defining Your Own Presentation Types". 



(flavorrmethod rpoint tv:graphics-mixin) x y Method 

Returns the numerical value of the picture element at the specified coordinates. 
The result is or 1 on a black-and-white TV. Clipping is performed; if the coordi- 
nates are outside the window, the result will be 0. 
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tv:pop-up-menu Flavor 

A combination of tvrmenu and tv:temporary-window-mixin, but does not have the 
automatic expose and deexpose features of tv:momentary-menu. See the section 
"Temporary Windows". It is appropriate to use a pop-up menu rather than a mo- 
mentary menu when you want to pop a menu up and make several choices from it 
before popping it back down. Another use is if you want to force the user to make 
a choice. Moving the mouse outside of the menu boundary does not deexpose the 
menu. 



tv:pop-up-multiple-menu-choose-menu Flavor 

A combination of tv:multiple-menu-choose-menu-mixin and tv:pop-up-menu. The 
arguments are the same as tv:multiple-menu-choose-menu. It accepts the rmulti- 
ple-choose message. 



tv:pop-up-multiple-menu-choose-resource Resource 

A resource of multiple-menu-choose menus. 

(flavorrmethod rposition tvrmenu) (left-edge top-edge) Init Option 

Specifies the left and top edges of the window. All specifications are given with re- 
spect to the outside of the superior window. 

(flavorrmethod rposition tvrsheet) Method 

Returns two values: the x and y positions of the upper-left corner of the window, 
in pixels, relative to the superior window, respectively. 

(flavorrmethod rposition tvrsheet) (left-edge top-edge) Init Option 

Specifies the x-coordinate of the left edge and the y-coordinate of the top edge of 
the window. 

rpreemptable token Option 

A blip in the input stream causes control to be returned from the input editor im- 
mediately. Two values are returned: the blip and token, which is usually a keyword 
symbol. Any unscanned input typed before the blip remains in the input buffer, 
available to the next read operation from the stream. 

tvrprepare-sheet {sheet) body... Function 

Prepares sheet for input or output. Ensures that sheet is not locked or in output- 
hold. Opens blinkers on inferiors and exposed superiors. 
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present object &optional (presentation-type (type-of dw::object)) &key (stream 
*standard-output*) (acceptably nil) (sensitive t) for-context-type (original-type nil) 
(form nil) (location nil) (single-box nil) (allow-sensitive-inferiors t) (allow-sensitive- 
raw-text t) Function 

Outputs a presentation object to a stream. The manner in which the object is dis- 
played depends on the presentation type of the object. If the stream supports pre- 
sentation remembering, the presented object is accessible via the mouse in the ap- 
propriate input context; if not, the printed representation is the same, but the ob- 
ject is not mouse-sensitive. 

object The object to be presented. 

presentation-type The presentation type to be used in presenting the ob- 

ject; the default is the type of the object. 

rstream Specifies stream on which the object is presented; the default is 
*standard-output*. 

racceptably Specifies when t to present the object in such a way 

that it can later be parsed by accept; the default is nil. A third 
possible value, :very, is for use with :for-context-type. This option 
is useful when output is to strings or files, but not necessary when 
output is to Dynamic Windows. 

: sensitive 

Boolean option specifying whether the presentation is mouse- 
sensitive; the default is t. This option is useful for explicitly pre- 
venting mouse sensitivity of objects presented to Dynamic Windows. 

:form Specifies a form that can be passed to setf to store a new value in 
place of the current output value. This option and rlocation are mu- 
tually exclusive. 

The form supplied for this option is used by a predefined, side- 
effecting mouse handler (available on c-n-Right) to modify the con- 
tents of structure slots. 

:for-context-type Specifies the context in which the presentation is to be 

presented with racceptably rvery. The most often used value is 
' ((cp:command-or-form : dispatch-mode : form-preferred))), which 
causes presentations of the type cprcommand to be printed with a 
leading colon. 

:original-type The original type supplied, to be passed through in 

successive recursive calls to present (or present-to-string or 
accept). 

rlocation Specifies a locative that can be used to store a new value in place 
of the current output value. This option and rform are mutually ex- 
clusive. 
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The locative supplied for this option is used by a predefined, side- 
effecting mouse handler (available on c-n-Right) to modify the con- 
tents of structure slots. 

:single-box Specifies that mouse-sensitivity of objects output in a 

series of inferior calls to this form be indicated by a single, large 
box for highlighting rather than the sum of all the individual boxes. 
This option is used mostly with graphic presentations. 

rallow-sensitive-inferiors Boolean option specifying whether nested 

calls to present or dw:with-output-as-presentation from inside this 
presentation — for example, when presenting the individual ele- 
ments of a Lisp list — generate presentation objects. The default is 
t. 

For an example, see the function dw:with-output-as-presentation. 

:allow-sensitive-raw-text Boolean options specifying when t that 

raw text, that is, the individual characters that make up the pre- 
sentation, are to be mouse-sensitive. 

For an overview of present and related facilities: See the section "Using Presenta- 
tion Types for Output". 



dw:presentation-blip-case blip &body clauses Function 

Dispatches to clauses based on the presentation-type field of a presentation blip. 

blip The presentation blip. 

clauses The case clauses. 

This macro is similar to the case special form, and could be written as 

(case (dw:presentation-bl ip-presentati on-type blip) 
<clauses>) 

but with one exception: comparison of the extracted presentation type with the 
types used as keys to the clauses is based on dwrpresentation-subtypep, not eql. 

Normally, you would not use this macro directly. See the function dwrwith- 
presentation-input-context. 

For an overview of dw:presentation-blip-case and related facilities: See the sec- 
tion "Presentation Input Blip Facilities". 

dw:presentation-blip-ecase blip &body clauses Function 

Dispatches to clauses based on the presentation-type field of a presentation blip. 

blip The presentation blip. 
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clauses The ecase clauses. 

This macro is similar to the ecase special form, and could be written as 

(ecase (dw:presentation-bl ip-presentati on-type blip) 
<clauses>) 

but with one exception: comparison of the extracted presentation type with the 
types used as keys to the clauses is based on dwrpresentation-subtypep, not eql. 

Normally, you would not use this macro directly. See the function dwrwith- 
presentation-input-context. 

For an overview of dw:presentation-blip-ecase and related facilities: See the sec- 
tion "Presentation Input Blip Facilities". 



dw:presentation-blip-mouse-char presentation-blip Function 

Returns the mouse character from a presentation blip. 

presentation-blip The presentation blip. 

For an overview of dw:presentation-blip-mouse-char and related facilities: See the 
section "Presentation Input Blip Facilities". 

dw:presentation-blip-object presentation-blip Function 

Returns the presentation object from a presentation blip. 

presentation-blip The presentation blip. 

For an overview of dw:presentation-blip-object and related facilities: See the sec- 
tion "Presentation Input Blip Facilities". 

dw:presentation-blip-options presentation-blip Function 

Returns the options field (a list of keyword-value pairs) of a presentation blip. 

presentation-blip The presentation blip. 

The options inserted in a presentation blip are obtained from the values returned 
by translating mouse handlers. A standard blip option is ractivate, which can be 
used by a translator to promote or prevent activation of the current field, that is, 
a return from the current call to accept. (See the function define-presentation- 
translator.) 

For an overview of dw:presentation-blip-options and related facilities: See the 
section "Presentation Input Blip Facilities". 

dw:presentation-blip-p blip Function 
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Determines whether a blip is a presentation blip. 

blip The blip. 

For an overview of dw:presentation-blip-p and related facilities: See the section 
"Presentation Input Blip Facilities". 

dw:presentation-blip-presentation-type presentation-blip Function 

Returns the presentation type from a presentation blip. 

presentation-blip The presentation blip. 

For an overview of dw:presentation-blip-presentation-type and related facilities: 
See the section "Presentation Input Blip Facilities". 

dw:presentation-blip-typep blip type Function 

Determines whether the presentation type of a presentation blip is of a specified 
type. (The comparison is based on dwrpresentation-subtypep). 

blip The presentation blip. 

type The presentation type with which the type of the blip is compared. 

For an overview of dw:presentation-blip-typep and related facilities: See the sec- 
tion "Presentation Input Blip Facilities". 

dw:presentation-equal presentation-1 presentation-2 Function 

Determines whether two presentations are "equal", that is, whether they are pre- 
senting the same object in the same manner. 

presentation-1 The first presentation. 

presentation-2 The second presentation. 

For an overview of dw:presentation-equal and related facilities: 
See the section "Defining Your Own Presentation Types". 

dw: *presentation-input-context* Variable 

Bound to the current presentation input context. 

An input context is a list of the form (presentation-type superior-context throw- 
flag . options). Each time a new input context is established, it becomes the new 
top-level context, enclosing the previous top-level context. (See the function 
dw:with-presentation-input-context.) Thus, there may be a hierarchy of contexts. 
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For example, if you have a presentation type microcode-version whose parser is 
defined as follows 

(def ine-presentati on-type microcode-version () 
: parser ((stream) 

(accept 'integer : stream stream)) 
:printer ((object stream) 

(princ object stream))) 

the call (accept '((microcode-version))) results in the following input context: 

(INTEGER (MICROCODE-VERSION NIL T : INHERIT T) T : INHERIT T) 

The initial call to accept establishes the MICROCODE-VERSION context and calls the 
parser for microcode-version. The parser calls accept with the presentation type 
integer, and accept establishes a new context for INTEGER; the new context con- 
tains the old context for MICROCODE-VERSION. 

For an overview of dw:*presentation-input-context* and related facilities: See the 
section "Presentation Input Context Facilities". 



dw:presentation-input-context-option presentation-input-context indicator Function 

Extracts the value of the specified option from an input context. The input context 
options are supplied in the options clause to dw:with-presentation-input-context. 

presentation-input-context Specifies the input context. 

indicator Specifies the name of the option to be extracted from the input 
context. 

For an overview of dw:presentation-input-context-option and related facilities: 
See the section "Presentation Input Context Facilities". 



dwrpresentation-subtypep subtype supertype Function 

Determines whether one presentation type is a subtype of another presentation 
type and encaches the result of the lookup. 

subtype The putative subtype presentation type. 
supertype The putative supertype presentation type. 

This function is the presentation system equivalent of the Common Lisp function 
subtypep. As does the latter, it returns two values: the first indicates whether the 
first type is a subtype of the second; the second whether the first result is certain. 
Three combinations are possible: 

t t subtype is definitely a subtype of supertype 

nil t subtype is definitely not a subtype of supertype 

nil nil the relationship could not be determined with certainty 
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One use of this function is in the rtester forms of mouse handlers. Although it is 
generally more convenient to use dw:handler-applies-in-limited-context-p, more 
complex testers may need dwrpresentation-subtypep, on which the former is 
based: 

(defun handler-appl ies-in-1 imited-context-p 
(context limiting-context-type) 
(let ((context-type 

(presentati on-i nput-context-presentati on-type 
context))) 
(presentati on-subtypep 
con text- type 1 i mi ting-con text- type))) 

See the function dw:handler-applies-in-limited-context-p. See the section "Defin- 
ing Your Own Presentation Types". 

For an overview of dwrpresentation-subtypep and related facilities: See the sec- 
tion "Programming the Mouse: Writing Mouse Handlers". 



dwrpresentation-subtypep-cached subtype supertype Function 

Obsolete. Use instead the function 

dwrpresentation-subtypep. 

dwrpresentation-type-default presentation-type Function 

Returns the current default — the object at the top of the type history — for a 
presentation type, if the type supports a history; otherwise, it returns nil. 

presentation-type The presentation type. 

Example: 

(dw : presentati on-type-def aul t ' pathname) 
==>#P" Y : >reg>saved-mai 1 >ui >def pgm . babyl . newest" 
FS:LMFS-PATHNAME 
T 

For an overview of dwrpresentation-type-default and related facilities: 
See the section "Defining Your Own Presentation Types". 

dwrpresentation-type-name type Function 

Returns the name of the presentation type from a presentation-type specification. 

type The type specification. 

Example: 
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(dw: presentation-type-name '((pathname) :dont-merge-defaul t nil)) 
PATHNAME 

For an overview of dw:presentation-type-name and related facilities: 

See the section "Defining Your Own Presentation Types". 

dw:presentation-type-p type Function 

Returns the presentation type descriptor if its argument is a presentation type, nil 
otherwise. If the argument is a user-defined flavor, the descriptor of that type is 
returned. If it is a user-defined structure, t is returned. 

type An object. 

Example: 

(dw:presentation-type-p '((integer 1 10))) 

=> #<DW:PRESENTATION-TYPE-DESCRIPTOR INTEGER 42516527> 

(dw : presentati on-type-p ' dw : dynami c-wi ndow) 

=> #<DW:PRESENTATION-TYPE-DESCRIPTOR DW: DYNAMIC-WINDOW 42506626> 

(def flavor a-flavor () ()) 

(dw : presentati on-type-p ' a-f 1 avor) 

=> #<FLA\/0R A-FLAVOR 1230276> 

For an overview of dw:presentation-type-p and related facilities: 

See the section "Defining Your Own Presentation Types". 

present-to-string object &optional (presentation-type (type-of dw::object)J &key 
(original-type dwrpresentation-typej (string nil) (index nil) acceptably for-context- 
type Function 

Outputs a presentation object to a string or returns a new string. 

object The object to be presented. 

presentation-type The presentation type to be used in presenting the ob- 

ject; the default is the type of the object. 

rstring Specifies a string to which the object is presented. The default is 
nil, causing a new string object to be created and returned as the 
value. 

rindex The character position in the string array where the presenting of 
the object begins; the default is position 0. Use this option only if 
the rstring option is non-nil. 

racceptably Specifies when t that the object should be presented in 

such a way that it can later be parsed by accept; the default is nil. 
A third value, rvery is for use with :for-context-type. 
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:for-context-type Specifies the context in which the presentation is to be 

presented with acceptably :very. The most often used value is 
' ((cp:command-or-form : dispatch-mode : form-preferred))), which 
causes presentations of the type cprcommand to be printed with a 
leading colon. 

:original-type The original type supplied, to be passed through in 

successive recursive calls to present (or present-to-string or 
accept). 

For an overview of present-to-string and related facilities: See the section "Using 
Presentation Types for Output". 



(flavor:method :primitive-item tv:basic-mouse-sensitive-items) type item left top 
right bottom Method 

The primary means for creating a mouse-sensitive-area of the screen. It creates a 
mouse-sensitive item of type type with associated object item. When the mouse 
moves into the area, a box is overlaid around it. left, top, right, and bottom are the 
coordinates of a rectangular area of the window assumed to contain the display. 
The coordinates are "inside" coordinates. This is the same coordinate system that 
:read-cursorpos uses. 



time:print-brief-universal-time ut &optional (stream standard-output) (ref-ut (zl- 
user:get-universal-time)) Function 

Like time:print-universal-time except that it omits seconds and only prints those 
parts of ut that differ from ref-ut, a universal time that defaults to the current 
time. Thus the output will be in one of the following three forms: 

02:59 ;the same day 

3/4 14:01 ;a different day in the same year 

8/17/74 15:30 ; a different year 



time:print-current-date &optional (stream standard-output) Function 

Prints the current time, formatted as in Friday the twenty-fifth of November, 
1988; 3:50:41 pm, to the specified stream. 



time:print-current-time &optional (stream standard-output) Function 

Prints the current time, formatted as in 11/25/83 14:50:02, to the specified stream. 



time:print-date seconds minutes hours day month year day-of-the-week &optional 
(stream standard-output) Function 
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Prints the specified time, formatted as in Friday the twenty-fifth of November, 
1983; 3:50:41 pm, to the specified stream. 



(flavor:method :print-function tv:function-text-scroll-window) Method 

Returns the window's printing function. 

(flavor:method :print-function-arg tv:function-text-scroll-window) Method 

Returns the object which the window passes as the second argument to the print 
function. 



time:print-interval-or-never interval &optional (stream zhstandard-output) 

Function 

Prints the representation of interval as a time interval onto stream. If interval is 
nil, it prints "Never", interval should be a nonnegative integer, or nil. 



:print-item item line-no item-no Message 

A text scroll window sends itself this message to display item on a line of the 
screen, line-no is the number of the line on the screen, and item-no is the number 
of the item in the list of items. When this message is sent, the cursor is already 
positioned to the beginning of line line-no; your method should send stream output 
messages to the window (that is, to self) to print item. 

For "mouse-sensitive items" within the "item", send :item to self. 



time:print-time seconds minutes hours day month year &optional (stream standard- 
output) Function 

Prints the specified time, formatted as in 11/25/83 14:50:02, to the specified 
stream. 



time:print-universal-time ut &optional (stream standard-output) timezone 

Function 

Prints the specified time, formatted as in 11/25/83 14:50:02, to the specified 
stream. 



time:print-universal-date ut &optional (stream standard-output) timezone 

Function 

Prints the specified time, formatted as in Friday the twenty-fifth of November, 
1983; 3:50:41 pm, to the specified stream. 
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(flavorrmethod rprocess tv:process-mixin) (initial-function . options) Init Option 

initial-function is called in the window's process with the window as its argument. 
options are options to make-process. 



tv:process-mixin Flavor 

Creates a new process associated with each window of the dependent flavor. (The 
Dynamic Window flavor dw:program-frame, used by dw: def ine-progr am- 
framework, includes this mixin.) 



dw:*program* Variable 

Bound to the currently active instance of a program flavor (created via dwrdefine- 
progr am-f r amework) . 

For an overview of dw:*program* and related facilities, see the section "Defining 
Your Own Program Framework". 



dw:program-command-table program Function 

Returns the command table used by an instance of a program flavor (created via 
dw: def ine-progr am-f r amework) . 

program The program instance. (The currently active program instance can 
be accessed as the value of dw:*program*.) 

For an overview of dw:program-command-table and related facilities, see the sec- 
tion "Defining Your Own Program Framework". 



dw:*progr am-f rame* Variable 

Bound to the program frame associated with the current instance of a program fla- 
vor (created via dw: def ine-progr am-f r amework). 

Use this variable for access to the program frame from a generic function or 
method of the program flavor, or from a program command definition macro. 

Example (for a program flavor named "my-program"): 

(def i ne-my-program-command (com-enabl e-secondary-commands 

: menu-accelerator "More Commands" 
:menu-level :main) 


(send dw:*program-f rame* : set-configuration 'secondary)) 

For access to a particular pane of the program frame, send a :get-pane message to 
dw:*progr am-f rame* or use dw:get-program-pane. 

For an overview of dw:*progr am-f rame* and related facilities, see the section 
"Defining Your Own Program Framework". 



Page 1344 



dw:program-frame Flavor 

The flavor used by dwrdefine-program-framework for the program frames it cre- 
ates. dw:program-frame is the Dynamic Window equivalent of tvrconstraint- 
frame-with-shared-io-buffer, which it incorporates as one of its component flavors; 
another component flavor is tv:process-mixin. Generally, you do not make direct 
use of this flavor; that you leave up to dwrdefine-program-framework. 

Init options, methods, and messages for this flavor include all of those for 
tv:constraint-frame-with-shared-io-buffer:See the section "Frames". The following 
are additional init options: 

rlabel See the section "Window Labels". 

rmargin-components See the flavor dw: dynamic- window. 

rprocess See the section "Windows and Processes". Normally you automatical- 
ly get a process running the program's top-level function when you 
program an application using dwrdefine-program-framework. 

rprogram The name of the program for which this is the program frame. 

:query-io-pane Specifies the pane to which *query-io* is bound when 

an instance of the program frame is active. 

:size-from-pane Specifies the pane on which to base the size of the 

program frame. 

:terminal-io-pane Specifies the pane to which *terminal-io* is bound 

when an instance of the program frame is active. 

For an overview of dw:program-frame and related facilities: See the section "Win- 
dow Substrate Facilities". 



dw:program-frame Resource 

A resource of program frames (of the kind used by 
dwrdefine-program-framework). The resource is created via tvrdefwindow- 
resource with the rinitial-copies option set to nil and the :reuseable-when option 
set to rdeactivated. (For more information on resources generally: See the section 
"Resources".) 

In addition to the required argument program-name and the optional argument su- 
perior (the frame's superior), the following keyword options are available when al- 
locating from or using the program frame resource: 

:temporary-p Boolean option specifying whether the frame provided 

is temporary, that is, whether it locks the superior window until it 
is deactivated. 

rprocess The process associated with the frame or nil, for no associated pro- 
cess. The default process is that of the program for which this 
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frame was created (by dwrdefine-program-framework). You can, for 
example, set this option to nil to run a program in you own process. 

When using this resource, you must supply the name of the program whose frame 
is to be provided. In the following example, a Frame-Up Layout Designer frame is 
specified. 

Example: 

(defun pf-resource () 

(using-resource (my-pf dw: program-frame 'dw: : layout-designer) 
(send my-pf : expose))) 



rprompt &rest prompt-option Option 

When it is time for the user to be prompted, the input editor displays prompt- 
option, prompt-option can have one element, which can be nil, a string, a function, 
or a symbol other than nil; or it can have more than one element: See the section 
"Displaying Prompts in the Input Editor". 

The difference between rprompt and rreprompt is that the latter does not display 
the prompt when the input editor is first entered, but only when the input is re- 
displayed (for example, after a screen clear). If both options are specified, 
rreprompt overrides rprompt except when the input editor is first entered. 



prompt-and-accept presentation-type-or-args &optional format-string &rest format- 
args Function 

Prompts for and accepts user input. (This function is similar to accept; it differs 
in that it uses the format function for creating the input prompt.) 

presentation-type-or-args Presentation type of the input object or, 

alternatively, a list of keyword-value pairs. 

Available keywords are the same as those for accept with one ex- 
ception. This is the rtype keyword, specifying the presentation type 
of the input object. If keywords are provided, one of them must be 
rtype. 

format-string Control string for the format function. 

format-args Arguments for the format specifiers included in the 

format-string. 

Example: 

(let ((x 5) (y 9)) 

(prompt-and-accept 'integer "Value for cell ~D ~D" x y)) 

For an overview of prompt-and-accept and related facilities: See the section "Us- 
ing Presentation Types for Input". 
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prompt-and-read type &optional format-string &rest format-args Function 

Prompts the user, with format-string and its arguments as the prompt. It uses 
zhformat to zl:query-io to produce the prompt; it reads from the zl:query-io 
stream, calling the reading function associated with the type keyword. If format- 
string is not specified, it generates a prompt appropriate to type. The type argu- 
ment can be a list in which the first element is the type keyword and the rest are 
keyword/value pairs to serve as arguments to the reading function. (For the 
robject and :object-list types, type must be a list with the :class keyword sup- 
plied.) prompt-and-read returns whatever the reading function returns. 

This function is obsolete. The function accept should be used to perform this op- 
eration. 

(prompt-and-read :number "Please enter a number: ") => 

Please enter a number: 4 

4 

(prompt-and-read :string "Please enter a string: ") => 

Please enter a string: 4 

" 4 " 

It expects to collect input of type type, where type is a keyword. It handles the fol- 
lowing types of input: 

Option Action 

:eval-form Reads a Lisp form. Evaluates it and returns the first value. 

Asks for confirmation of nonconstant values. The Debugger us- 
es this to prompt for a form to evaluate. 

:eval-form-or-end Reads a Lisp form or just END. Evaluates it and returns the 
first value for a form. Returns two values, nil and rend, for 
END. Asks for confirmation of nonconstant values. The Debug- 
ger uses this to prompt for a form to evaluate. 

rexpression Reads a Lisp expression and returns the expression without 

evaluating it. 

:expression-or-end Reads a Lisp expression or just END. It returns the expression 
without evaluating it. If the user just presses END, it returns 
two values, nil and rend. 

rcharacter Reads and returns a character. The returned value is a charac- 

ter code (an integer). 

rsymbol Reads and returns a symbol. 

(:function-spec :defined-p defined-p) Reads and returns a function spec. If 
:defined-p is specified with a value other than nil, the function 
spec must be defined as a function. The default for defined-p is 
nil. 

rstring Reads a string terminated by RETURN, LINE, or END. It returns 

the empty string when the string is empty. 
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:string-trim Reads a string terminated by RETURN, LINE, or END. It trims 

any leading or trailing white space. It returns the empty string 
when the string is empty. 

:string-or-nil Reads a string terminated by RETURN, LINE, or END. It trims 

any leading or trailing white space. It returns nil when the 
string is empty. 

(:string-list :or-nil or-nil) Reads a series of strings separated by commas and ter- 
minated by RETURN, LINE, or END. It returns a list of the 
strings, unless or-nil is not nil and the user just presses RE- 
TURN, LINE, or END. In that case it returns nil. The default for 
or-nil is t. 

(rdelimited-string rdelimiter delimiter rvisible-delimiter visible-delimiter rbuffer- 
size size :or-nil or-nil) Reads characters until the 

user types a delimiter, then returns the input as a string with- 
out the delimiter. 

rdelimiter and rvisible-delimiter are mutually exclusive. If one 
of them is specified, it must be nil or a list of characters that 
delimit the string. If neither is specified, or if one is specified 
with a value of nil, the only delimiter is #/End. 

The difference between rdelimiter and rvisible-delimiter is 
that if a prompt is supplied as the second argument to 
prompt-and-read, the rvisible-delimiter characters are dis- 
played to the user after the prompt, but the rdelimiter charac- 
ters is not. If a prompt is supplied and neither rdelimiter nor 
rvisible-delimiter is specified, the delimiting character is not 
displayed. If no prompt is supplied, the delimiting characters 
are always displayed, whether they come from rdelimiter, 
rvisible-delimiter, or the default delimiter. 

If rbuffer-size is specified, an initial buffer of size size charac- 
ters is allocated; otherwise, the initial size is 100. characters. 
It returns the empty string when the string is empty, unless 
ror-nil is specified with a value other than nil. In that case it 
returns nil when the string is empty. The default for or-nil is 
nil. 

(rdelimited-string-or-nil rdelimiter delimiter rvisible-delimiter visible-delimiter 
rbuffer-size size) The same as (delimited-string rdelimiter 

delimiter rvisible-delimiter visible-delimiter rbuffer-size size 
ror-nil t ). This option is obsolete. 

(rcomplete-string ralist alist rdelimiters delimiters rimpossible-is-ok impossible-is- 
ok ror-nil or-nil rcomplete-on-space complete-on-space) 
Reads and returns a (possibly completed) string, terminated by 
RETURN, LINE, or END. 
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If the user presses COMPLETE, the input so far is completed 
over the set of possibilities determined by alist. If complete-on- 
space is not nil, the input is also completed when the user 
presses SPRCE at the end of the input buffer. The default for 
complete-on-space is t. 

If the user presses c-?, the possible completions of the input 
are displayed. If the user presses HELP, the possible comple- 
tions are displayed unless many exist; in that case a general 
help message is displayed. 

The style of completion is the same as that offered by Zwei. al- 
ist can be nil, an alist, an sys:art-q-list array, or a keyword: 

nil No completion is offered. This is the de- 

fault. 

alist The car of each alist element is a string 

representing one possible completion. 

array Each element is a list whose car is a string 

representing one possible completion. The 
array must be sorted alphabetically on the 
cars of the elements. 

keyword If the symbol is rzmacs, completion is of- 

fered over the definitions in Zmacs buffers. 
If the symbol is rflavors, completion is of- 
fered over all flavor names. If the symbol 
is : documentation, completion is offered 
over all documentation topics available to 
Document Examiner. 

Example: 

(prompt-and-read 

' ( : complete-string :alist : documentation)) 
Enter a string with completion, or <RETURN> 
for none: formatted output 
=> "Formatted Output" 
=> (("Formatted Output" DOC: | FORMATTED OUTPUT |)) 

delimiters is nil or a list of characters that delimit "chunks" 
for completion. As in Zwei, completion works by matching ini- 
tial substrings of "chunks" of text. If delimiters is nil, the en- 
tire text of the input is a single "chunk". The default is nil. 

If or-nil is nil and the user just presses RETURN, LINE, or END, 
rcomplete-string waits for more input. If or-nil is not nil and 
the user just presses RETURN, LINE, or END, it returns nil. The 
default for or-nil is t. 
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If the user presses RETURN, LINE, or END and the input buffer 
is not empty, the input is completed as far as possible. If the 
completed string is the car of an alist element, the completed 
string is returned. Otherwise, if the user pressed END or if im- 
possible-is-ok is nil, rcomplete-string waits for more input. If 
the user pressed RETURN or LINE and if impossible-is-ok is not 
nil, the completed string is returned. The default for impossi- 
ble-is-ok is t. 

Unless rcomplete-string returns nil, it also returns a second 
value, a list of the alist elements that represent possible com- 
pletions of the returned string. 

(rflavor-name :impossible-is-ok impossible-is-ok) Reads and returns the 

name of a flavor, terminated by RETURN, LINE, or END. The user 
can type the flavor name with or without a package prefix. 

If the user presses COMPLETE, the input so far is completed 
over the set of defined flavors. If the user presses c-?, the 
possible completions of the input are displayed. If the user 
presses HELP, the possible completions are displayed unless 
many exist; in that case a general help message is displayed. 

If the user presses RETURN, LINE, or END and the input buffer 
is not empty, the input is completed as far as possible. If the 
completed input is the name of a flavor, the flavor name (a 
symbol in the appropriate package) is returned. Otherwise, if 
the user pressed END, rflavor-name waits for more input. If the 
user pressed RETURN or LINE and if impossible-is-ok is not nil, 
the completed input is returned as a symbol. If the user 
pressed RETURN or LINE and if impossible-is-ok is nil, an error 
is signalled and caught by the input editor. The default for im- 
possible-is-ok is t. 

(mumber rbase input-base :or-nil or-nil) Reads and returns a number, terminated 
by RETURN, LINE, or END. If rbase is specified, the number is 
read in base input-base; otherwise, it is read as a decimal 
number. If :or-nil is specified with a value other than nil, it 
returns nil if the user just presses RETURN, LINE, or END. The 
default for or-nil is nil. 

(:number-or-nil rbase input-base) The same as (muniber rbase input-base 

ror-nil t ). This option is obsolete. 

(r decimal-number ror-nil or-nil) The same as (muniber rbase 10. ror-nil 

or-nil). This option is obsolete. 

rdecimal-number-or-nil The same as (muniber rbase 10. ror-nil t ). This op- 
tion is obsolete. 

(rinteger rbase input-base ror-nil or-nil rfrom from rto to) Reads and re- 

turns an integer, terminated by RETURN, LINE, or END. If rbase 
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is specified, the integer is read in base input-base; otherwise, it 
is read as a decimal number. If :or-nil is specified with a value 
other than nil, it returns nil if the user just presses RETURN, 
LINE, or END. The default for or-nil is nil. If :from is specified, 
the integer must be greater than or equal to from. If :to is 
specified, the integer must be less than or equal to to. The de- 
fault for from and to is to place no limits on the integer. 

(relate :past-p past-p :never-p never-p :base-time base-time :or-nil or-nil) 

Reads and returns a date, terminated by RETURN, LINE, or END. 
The returned date is a universal-time integer of the form re- 
turned by time:parse-universal-time. If :past-p is specified 
with a value other than nil, an ambiguous date is interpreted 
as being in the past, relative to the base time; otherwise, it is 
interpreted as being in the future. The default for past-p is nil. 
If :never-p is specified with a value other than nil, it returns 
nil if the user types "never". The default for never-p is nil. If 
:base-time is specified, it must be a universal-time integer that 
is used to fill in components that the user omits. If :base-time 
is not specified, the time when the user's input is read is used 
as the base time. 

(:past-date :never-p never-p :base-time base-time :or-nil or-nil) The same as 

(relate :past-p t :never-p never-p :base-time base-time :or-nil 
or-nil). This option is obsolete. 

(:date-or-never :past-p past-p :base-time base-time :or-nil or-nil) The same as 

(relate :past-p past-p :never-p t :base-time base-time :or-nil or- 
nil). This option is obsolete. 

(:past-date-or-never :base-time base-time :or-nil or-nil)The same as (:date :past-p 
t :never-p t :base-time base-time :or-nil or-nil). This option is 
obsolete. 

:time-interval-or-never Reads a time interval, terminated by RETURN, LINE, or 
END. The interval must be either "never" or alternating num- 
bers and units of time; the units can include seconds, minutes, 
hours, days, weeks, or years. It returns nil if the user types 
"never". Otherwise, it returns an integer representing the num- 
ber of seconds in the time interval. 

Example: 

(prompt-and-read : time- interval -or-never) 

Enter a time interval, or "never": 1 day 2 hrs 13 min => 

94380. 

(rpathname rdefault default rvisible-default visible-default : default- version version 
:or-nil or-nil) Reads a pathname, terminated by RETURN, 

LINE, or END, merging it with a default. 
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rdefault and rvisible-default are mutually exclusive. If either 
is specified, its value can be nil, a pathname, a pathname 
string, or an alist of hosts and pathnames of the sort that is 
the value of fsr*default-pathname-defaults*. If the value is nil 
or a defaults alist, the default used is the result of calling 
fsrdefault-pathname on the value. If the value is a pathname 
or a pathname string, the default used is the result of calling 
fsrparse-pathname on the value. If neither rdefault nor 
rvisible-default is specified, the default used is the result of 
(fsrdefault-pathname). 

The difference between rdefault and rvisible-default is that if 
a prompt is supplied as the second argument to prompt-and- 
read, the rvisible-default pathname is displayed to the user af- 
ter the prompt, but the rdefault pathname is not. If a prompt 
is supplied and neither rdefault nor rvisible-default is speci- 
fied, the default pathname is not displayed. If no prompt is 
supplied, the default pathname is always displayed, whether it 
comes from rdefault, rvisible-default, or the default default. 

If rdefault- version is not specified, the default version is nil. 
If rdefault- version is specified, its value should be an integer 
or keyword suitable as the third argument to fsrmerge- 
pathnames. 

If the user just presses RETURN or LINE this option returns the 
default pathname. If the user just presses END this option re- 
turns the default pathname, unless ror-nil is specified with a 
value other than nil. In that case it returns nil. Otherwise this 
option returns the pathname the user typed, merged against 
the default and the default version. The default for or-nil is 
nil. 

If the user presses COMPLETE an attempt is made to complete 
the pathname string typed so far. If the user presses END after 
typing some text, an attempt is made to complete the path- 
name string, and if completion is successful the merged path- 
name is returned. 

Example: 

(prompt-and-read 

'(: pathname : visible-default , my-defaul ts-al ist) 
"Enter a name")) 

(rpathname-or-nil rdefault default rvisible-default visible-default rdefault- version 
version) The same as (rpathname rdefault default rvisible- 
default visible-default rdefault- version version ror-nil t ). This 
option is obsolete. 

(rpathname-list rdefault default rvisible-default visible-default ror-nil or-nil) 

Reads a series of pathnames, separated by commas and termi- 
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nated by RETURN, LINE, or END. The meaning of rdefault and 
rvisible-default is the same as for the rpathname option. 
:pathname-list merges the pathnames with the default and 
with a default version of mewest. It returns a list of the 
merged pathnames, unless or-nil is not nil and the user just 
presses RETURN, LINE, or END. In that case it returns nil. The 
default for or-nil is t. 

(:host :host-type type rdefault default :or-nil or-nil) Reads the name of a host, 
terminated by RETURN, LINE, or END. 

:host-type is a keyword that determines what kind of input is 
acceptable: 

rphysical The name of a network host. This is the 

default. 

:chaos-only The name of a network host on the chaos- 

net. 

:or-local The name of a network host or "local", 

meaning the local host. 

rpathname The name of a pathname host or "local", 

meaning the local host. 

:or-pathname The name of a network host, a pathname 

host, or "local", meaning the local host. 

If rdefault is specified, it should be a network host or the 
name of a host as a symbol or string. If rdefault is specified 
and the user just presses RETURN, LINE, or END, it returns the 
host specified by rdefault. 

If rdefault is not specified or is nil, ror-nil is specified with a 
value other than nil, and the user just presses RETURN, LINE, 
or END, it returns nil. Otherwise, it returns the host object 
whose name the user types. The default for or-nil is nil. 

(rhost-or-local rdefault default ror-nil or-nil) The same as (rhost rhost- 

type ror-local rdefault default ror-nil or-nil). This option is ob- 
solete. 

(rpathname-host rdefault default ror-nil or-nil) The same as (rhost rhost- 

type rpathname rdefault default ror-nil or-nil). This option is 
obsolete. 

(rhost-list rhost-type host-type ror-nil or-nil) Reads a series of names of 

network hosts, separated by spaces or commas, and terminated 
by RETURN, LINE, or END. rhost-type has the same meaning as 
for the rhost option, rhost-list returns a list of the host objects 
whose names the user types, unless or-nil is not nil and the 
user just presses RETURN, LINE, or END. In that case it returns 
nil. The default for or-nil is t. 
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(rkeyword :or-nil or-nil) Reads the name of a symbol to be interned in the 
keyword package, terminated by RETURN, LINE, or END. The 
symbol name should not have a package prefix (that is, it 
should not be preceded by a colon). Lowercase letters in the 
name are converted to upper case, rkeyword returns the key- 
word symbol whose name the user types, unless :or-nil is spec- 
ified with a value other than nil and the user just presses RE- 
TURN, LINE, or END. In that case it returns nil. The default for 
or-nil is nil. 

(:keyword-list :or-nil or-nil) Reads a series of names of symbols to be 

interned in the keyword package, separated by spaces or com- 
mas, and terminated by RETURN, LINE, or END. The symbol 
names should not have package prefixes (that is, they should 
not be preceded by colons). Lowercase letters in the names are 
converted to upper case. :keyword-list returns a list of key- 
word symbols whose names the user types, unless or-nil is not 
nil and the user just presses RETURN, LINE, or END. In that case 
it returns nil. The default for or-nil is t. 

(:font :or-nil or-nil)Reads the name of a font, terminated by RETURN, LINE, or END. 
The font name should not have a package prefix (that is, it 
should not be preceded by fonts:), and it must be the name of 
a known font. :font returns the font (not the symbol) whose 
name the user types, unless :or-nil is specified with a value 
other than nil and the user just presses RETURN, LINE, or END. 
In that case it returns nil. The default for or-nil is nil. 

(:font-list :or-nil or-nil) Reads a series of names of fonts, separated by spaces 
or commas, and terminated by RETURN, LINE, or END. The font 
names should not have package prefixes (that is, they should 
not be preceded by fonts:), and they must be names of known 
fonts. :font-list returns a list of the fonts (not the symbols) 
whose names the user types, unless or-nil is not nil and the 
user just presses RETURN, LINE, or END. In that case it returns 
nil. The default for or-nil is t. 

(:object :class class :or-nil or-nil) Reads the name of an object in the net- 

work namespace, terminated by RETURN, LINE, or END. class is a 
keyword representing a namespace class or a string that is the 
print name of a class keyword. You must supply this argument. 
:object returns the namespace object whose name the user 
types, unless :or-nil is specified with a value other than nil 
and the user just presses RETURN, LINE, or END. In that case it 
returns nil. The default for or-nil is nil. 

(:object-list :class class :or-nil or-nil) Reads a series of names of objects in the 
network namespace, separated by spaces or commas, and termi- 
nated by RETURN, LINE, or END. class is a keyword representing 
a namespace class or a string that is the print name of a class 



Page 1354 



keyword. You must supply this argument. :object-list returns a 
list of the namespace objects whose names the user types, un- 
less or-nil is not nil and the user just presses RETURN, LINE, or 
END. In that case it returns nil. The default for or-nil is t. 

(rclass :or-nil or-nil) Reads the name of a network namespace class, termi- 

nated by RETURN, LINE, or END. The name should not contain a 
package prefix (that is, it should not be preceded by a colon). 
It returns the keyword representing the class whose name the 
user types, unless :or-nil is specified with a value other than 
nil and the user just presses RETURN, LINE, or END. In that case 
it returns nil. The default for or-nil is nil. 

Streams are permitted to have a handler for :prompt-and-read messages. The 
prompt-and-read function first determines whether the zl:query-io stream handles 
the :prompt-and-read message. If so, it sends a :prompt-and-read message with 
its own arguments on to the stream. The stream returns several values. The first 
value the stream returns says whether or not it wants to handle the interaction 
with the user itself. It returns nil to indicate that it declines to handle the mes- 
sage, in which case the prompt-and-read function continues its normal action of 
prompting the user. When the first value is not nil, the prompt-and-read function 
returns the rest of the values to its caller. 



(flavorrmethod :put-item-in-window tvrtext-scroll-window) item Method 

The first occurrence of item is located. If it occurs before the first item in the 
window, the window redisplays so that item appears in the top line. If it occurs af- 
ter the last item in the window, the window redisplays so that item appears in the 
bottom line. 

If item is already visible or is not in the list, nothing happens. 



(flavorrmethod :put-last-item-in-window tvrtext-scroll-window) Method 

If the last item is not visible, the window redisplays so that the last item appears 
in the bottom line. 



cprread-accelerated-command &key (command-table cp:*command-table*) (stream 
*query-io*) (help-stream stream) (echo-stream stream) (whostate nil) (prompt nil) 
(command-prompt cp::*full-command-prompt*) (full-command-full-rubout nil) (spe- 
cial-blip-handler nil) (timeout nil) (input-wait nil) (input-wait-handler nil) (form-p 
nil) (handle-clear-input nil) (catch-accelerator-errors t) (unknown-accelerator-is- 
command nil) (unknown-accelerator-tester nil) (unknown-accelerator-reader nil) (un- 
known-accelerator-reader-prompt nil) (abort-chars nil) (suspend-chars nil) (status nil) 
(intercept-function nil) (window-wakeup nil) Function 

Reads a Command Processor command input as a single-key accelerator. 
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The values returned by this function depend on whether a command or form is ex- 
pected (see the :form-p option below). If the caller is expecting a command 
(:form-p is nil), the values returned are the command name, command arguments, 
and a flag. If the caller is expecting a form (:form-p is t), the values returned are 
the form and a flag. 

Possible values for the returned flag are: 

rcommand A command was read. 

rform A form was read. 

raccelerator An accelerator character was read. 

rtimeout A timeout expired. 

: status The window's status changed. 

rwakeup The window was asynchronously refreshed, selected, exposed, and so 
on. 

runknown (or nil) Something unknown was typed. 

cprread-accelerated-command accepts the following keyword options: 

:command-table Specifie&h©ommandabl©ontaining.h©ccelerator; 

the default is the current binding of cp:*command-table*. 

rstream Specifiesthestreamfrom which to read thecommand;thedefault 
is *query-io*. 

:help-stream Specifiestheoutputstreamforhelpmessages;thede- 

fault is the stream specified by the rstream option. 

recho-stream Specifiesthe stream to which theinputcommandis 

echoed; the default is the stream specified by the rstream option. 

To suppress echoing, supply this option with #'ignore. 

rwhostate Specifiesastringtoappearinthestatuslineinplace 

of "User Input". 

rprompt Specifies a string to be used as the prompt, or a prompt option. 
(See the section "Displaying Prompts in the Input Editor".) 

rcommand-prompt Specifies a string to be used as the prompt if a com- 
mand is to be read, that is, if the user types ":" or m-x. The default 
is cprr*full-command-prompt*, which is "Command: ". 

rfull-command-full-rubout BooleaHDptioispecifyingvhethetare- 

turn if CLERR INPUT is pressed (or a series RUBOUTs back to the 
prompt) after the command prompt (":" or n-H, for example) is 
typed. The default is nil, allowing the continuation of command 
parsing. 
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:special-blip-handler Specifiesafunctioncalledwithmouseblipsthatare 
not presentation input blips. (See the section "Mouse Blips".) 

rtimeout Specifies the length of time, in 60ths of a second, after which, if 

the user types nothing, cprread-accelerated-command returns 
rtimeout as the flag and nil for the other values. 

:input-wait Specifiesafunctiontestingforsomeconditionwhilein 

the input-wait state. If this condition occurs, the rinput-wait- 
handler is invoked. 

:input-wait-handler Specifiesafunctioncalledafteraconditionsatisfying 
the :input-wait function occurs. 

:form-p Booleanoptionspecifyingwhetheraformorcommandisexpected; 

the default is nil. If t, the function returns an evaluable form 
rather than the command name and arguments. 

:handle-clear-input Booleanoptionspecifyingwhether#/clear-inputis 

treated specially; the default is nil. If t and the CLERR INPUT key is 
pressed, the function clears the input buffer and reprompts. 

rcatch-accelerator-errors BooleanptioHpecifyinglietheisyhen 

an unknown accelerator character is typed, the function beeps and 
prints out a warning message; the default is t. If nil, the error fla- 
vor cp:: accelerator-error is signaled. 

:unknown-accelerator-is-command Specifiewshethaanknowdoccelerators 

are dispatched to the runknown-accelerator-reader function. 

The default is nil. Unknown accelerators that do not pass the 
runknown-accelerator-tester function give errors (which may or 
may not get through to the user — see the rcatch-accelerator- 
errors option). 

If t, all unknown accelerators dispatch to the unknown-accelerator 
reader which should return a command. 

A third value permitted for this option is ralpha, causing only un- 
known accelerators that are alphabetic characters to be dispatched 
to the unknown-accelerator reader. 

runknown-accelerator-tester Specifierfunctiorofineargumentthe 

character typed, which should return something non-nil if this par- 
ticular unknown accelerator is permitted. In this case, runknown is 
returned as the flag and the value from this function is the first 
value. If rform-p is nil, the character is returned as the second val- 
ue. 

runknown-accelerator-reader Specifierfunctioroncargumentithat 

should return a form. (The function can call cprread-command, 
etc., but it should return a form.) 
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runknown-accelerator-reader-prompt Specifiestrinjjpsas 

the prompt in this case, or a prompt option. (See the section "Dis- 
playing Prompts in the Input Editor".) 

:abort-chars Specifies a list of "abort" characters; the default is nil. 

If a list of characters is provided and the user types one, sysrabort 
is signalled. 

:suspend-chars Specifiesalistof'suspend"characters;thedefaultis 

nil. 

If a list of characters is provided and the user types one, a break 
loop is entered. 

: status Specifieswhathappensifthewindow'sstatuschanges.Threevalues 
are permitted, rselected, rexposed, and nil. 

If the value is rselected and the window is no longer selected, the 
function returns :status. 

If the value is rexposed and the window is no longer exposed or se- 
lected, the function returns rstatus. 

If the value is nil, the function continues to wait for input when 
the window is deexposed or deselected. This is the default. 

rintercept-function Specifiesafunctionofoneargumentacharacter,that 

gets called on each typed character that is one of rabort-chars or 
rsuspend-chars. 

rwindow-wakeup Boolearcptionspecifyingwhethertoreturrirwakeup 

when an asynchronous window system condition like expose, select, 
or refresh occurs; the default is nil. 

For an overview of cprread-accelerated-command and related facilities: See the 
section "Managing Your Program Frame". 



zl:read-and-eval &optional stream (catch-errors t) Function 

Calls zlrread-expression to read a form, without completion. It then evaluates the 
form and returns the result. If catch-errors is not nil, it calls zlrparse-ferror if an 
error occurs during the evaluation (but not the reading) so that the input editor 
catches the error. 

stream defaults to zlrstandard-input. This function is intended to read only from 
interactive streams. 



(flavorrmethod :read-bp sirinteractive-stream) Method 
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Returns the value of the scan pointer. This is for the benefit of read functions 
that might want to return a pointer into the input buffer when signalling an error 
of type sys:parse-error. 



dw:read-char-for-accept stream Function 

Returns the next character in the input stream and removes this character from 
the stream. 

stream The input stream. 

The character returned may be a presentation blip character containing informa- 
tion specific to the accept input mechanism. Therefore, characters read via 
dw:read-char-for-accept should only be manipulated by the related Dynamic Win- 
dow input functions. For example, you cannot use char-equal to compare a charac- 
ter returned by dw:read-char-for-accept with a standard character; you must use 
dw:compare-char-for-accept instead. 

For an overview of dw:read-char-for-accept and related facilities, see the section 
"Defining Your Own Presentation Types". 



sysrread-character &optional stream &key (fresh-line t) (any-tyi nil) (eof nil) (noti- 
fication t) (prompt nil) (help nil) (refresh t) (suspend t) (abort t) (status nil) presen- 
tation-context Function 

Reads and returns a single character from stream. This function displays notifica- 
tions and help messages and reprompts at appropriate times. It is used by fquery 
and the rcharacter option for prompt-and-read. 

stream must be interactive. It defaults to zl:query-io. 

Following are the permissible keywords: 

:fresh-line If not nil, the function sends the stream a :fresh-line message 

before displaying the prompt. If nil, it does not send a rfresh- 
line message. The default is t. 

:any-tyi If not nil, the function returns blips. If nil, blips are treated as 

the :tyi message to an interactive stream treats them. The de- 
fault is nil. 

:eof If not nil and the function encounters end-of-file, it returns 

nil. If nil and the function encounters end-of-file, it beeps and 
waits for more input. The default is nil. 

motification If not nil and a notification is received, the function displays 

the notification and reprompts. If nil and a notification is re- 
ceived, the notification is ignored. The default is t. 

rprompt If nil, no prompt is displayed. Otherwise, the value should be a 

prompt option to be displayed at appropriate times. See the 
section "Displaying Prompts in the Input Editor". The default 
is nil. 
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:help If not nil, the value should be a help option. See the section 

"Displaying Help Messages in the Input Editor". Then, when 
the user presses HELP, the function displays the help option 
and reprompts. If nil and the user presses HELP, the function 
just returns #\help. The default is nil. 

rrefresh If not nil and the user presses REFRESH, the function sends the 

stream a rclear-window message and reprompts. If nil and the 
user presses REFRESH, the function just returns #\refresh. The 
default is t. 

rsuspend If not nil and the user types one of the sysrkbd-standard- 

suspend-characters, a zlrbreak loop is entered. If nil and the 

user types a suspend character, the function just returns the 
character. The default is t. 

rabort If not nil and the user types one of the sysrkbd-standard- 

abort-characters, sysrabort is signalled. If nil and the user 
types an abort character, the function just returns the charac- 
ter. The default is t. 

: status This option takes effect only if the stream is a window. If the 

value is rselected and the window is no longer selected, the 
function returns :status. If the value is rexposed and the win- 
dow is no longer exposed or selected, the function returns 
:status. If the value is nil, the function continues to wait for 
input when the window is deexposed or deselected. The default 
is nil. 

rpresentation-context If this is not nil, the presentation system is enabled, 

that is, presentations that are targets of existing mouse han- 
dlers will be sensitive. 



cprread-command &optional (stream zl-userr*standard-input*) &key (command- 
table cp:*command-table*) (blank-line-mode cp::*default-blank-line-mode*) 
(prompt cprr*default-prompt*) Function 

Reads a Command Processor command from stream, terminated by RETURN or END. 

If stream is not supplied or is nil, it defaults to *clrstandard-input*. 

From the user's point of view, a command consists of a command name, positional 
arguments, and keyword arguments: See the section "Parts of a Command". 
cprread-command offers completion over command names, keyword argument 
names, and some argument values, and it completes any unspecified command com- 
ponents when the command is terminated: See the section "Completion in the Com- 
mand Processor". 

cprread-command prompts for arguments and gives information about what sort 
of values are expected. Some arguments have default values. The user can press 
HELP to see documentation appropriate to the current stage of entering the com- 
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mand: See the section "Help in the Command Processor". For a general description 
of how the user enters a command: See the section "Entering a Command". 

If :command-table is supplied, it is a command table of the acceptable commands. 
The default command table is the value of cp:*command-table*. The initial de- 
fault is the "User" command table. See the section "Command Processor Command 
Tables". 

If :blank-line-mode is supplied, it is a keyword that determines what action the 
command processor takes when the user types a blank line: 



rreprompt 


Redisplay the prompt, if any. 


:beep 


Beep. 


rignore 


Do nothing. 



The default blank-line-mode is the value of cp::*default-blank-line-mode*. The ini- 
tial default is rreprompt. 

If rprompt is supplied, it is a prompt option for the input editor to display at ap- 
propriate times, prompt can be nil, a string, a function, or a symbol other than nil 
(but not a list): See the section "Displaying Prompts in the Input Editor". The de- 
fault prompt is the value of cp::*default-prompt*. The initial default is "Com- 
mand: ". 

cprread-command returns two values. The first is a symbol, the name of the com- 
mand, which is defined as a function. The second is a list of the arguments, con- 
verted to the appropriate types. Usually you execute the command by applying the 
first value (the function) to the second (the arguments). 

For an overview of cprread-command and related facilities: See the section "Man- 
aging the Command Processor". 



cprread-command-arguments command-name &key initial-arguments {command- 
table cp:*command-table*) {stream *standard-input*) {prompt nil) Function 

Prompts for and returns the arguments to a Command Processor command. 

command-name The command name (symbol). 

rinitial-arguments Specifies a list containing zero or more of the initial 
arguments to the command. 

rcommand-table Specifies the command table containing the command; 

the default is the current command table (bound to cp:*command- 
table*). 

rstream Specifies the input stream; the default is *standard-input*. 

rprompt Specifies a string, or a function returning a string, to be used as 
the prompt for the command arguments. The default value for this 
option is nil, causing the prompt to be derived from the user-visible 
name of the command. 
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Example: 

(cp: read-command-arguments 'si :com-show-f ile : prompt 

"File for viewing") 

You can apply the command function to the arguments returned in order to exe- 
cute it. 

For an overview of cprread-command-arguments and related facilities: See the 
section "Managing Your Program Frame". 



cp:read-command-or-form &optional (stream zl-userr*standard-input*J &key (com- 
mand-table cpr*command-table*J (dispatch-mode cp::*default-dispatch-mode*J 
(blank-line-mode cp::*default-blank-line-mode*J (prompt cprr*default-prompt*J ex- 
ception-chars expression-reader expression-printer (environment sir*read-form- 
environment*) Function 

Reads a form or a Command Processor command from stream. This is an appropri- 
ate function to use at top level in a command loop that uses the command proces- 
sor. 

If stream is not supplied or is nil, it defaults to *clrstandard-input*. 

If :dispatch-mode is specified, it is a keyword that indicates the command proces- 
sor dispatch mode. The default is the value of cp::*default-dispatch-mode*. The 
initial default is rcommand-preferred. 

The actions that cp:read-command-or-form takes depend on dispatch-mode: 

:form-only Calls zlrread-form to read a form from stream. 

:command-only Calls cprread-command to read a command from stream. 

rform-preferred Calls zlrread-form unless the first character typed is a com- 
mand dispatch character (by default, a colon). In that case 
calls cprread-command. 

rcommand-preferred If the first character typed is a command dispatch 

character or an alphabetic character, calls cprread-command; 
otherwise, calls zlrread-form. The user can evaluate a form 
that begins with an alphabetic character by first typing a form 
dispatch character (by default, a comma). 

For a general description of how the user enters a command: See the section "En- 
tering a Command". 

If rcommand-table is supplied, it is a command table of the acceptable commands. 
The default command table is the value of cpr*command-table*. The initial de- 
fault is the "User" command table. See the section "Command Processor Command 
Tables". 

If rblank-line-mode is supplied, it is a keyword that determines what action the 
command processor takes when the user types a blank line: 
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rreprompt 


Redisplay the prompt, if any. 


:beep 


Beep. 


rignore 


Do nothing. 



The default blank-line-mode is the value of cp::*default-blank-line-mode*. The ini- 
tial default is rreprompt. 

If rprompt is supplied, it is a prompt option for the input editor to display at ap- 
propriate times, prompt can be nil, a string, a function, or a symbol other than nil 
(but not a list): See the section "Displaying Prompts in the Input Editor". The de- 
fault prompt is the value of cp::*default-prompt*. The initial default is "Com- 
mand: ". 

The keyword :exception-chars is for internal use. It is ignored by cprread- 
command-or-form. 

Possible values of the keywords rexpression-reader and rexpression-printer are 
functions for reading and writing expressions in languages other than Lisp, such 
as Pascal, Fortran, or C. These are for use by the debugger. 

cp:read-command-or-form returns a form. If cp:read-command-or-form calls 
zl:read-form to read from stream, it returns the form that zl:read-form returns. If 
it calls cprread-command, it returns a list whose first element is a symbol, the 
name of the command, which is defined as a function. The remaining elements of 
the list are the arguments to the command, coerced to the appropriate types. Usu- 
ally you execute the command by evaluating the returned list. 

For an overview of cp:read-command-or-form and related facilities: See the sec- 
tion "Managing the Command Processor". 



(flavorrmethod :read-cursorpos tvrblinker) Method 

Returns two values: the x and y components of the position of the blinker within 
the inside of the window. 



(flavorrmethod rread-cursorpos tvrsheet) &optional (units 'rpixelj Method 

Return two values: the x and y coordinates of the cursor position, that is, <x, y> is 
the upper left corner of the next character drawn. These coordinates are in pixels 
by default, but if units is rcharacter, the coordinates are given in character-widths 
and line-heights. (Note that character-widths don't mean much when you are using 
variable-width fonts.) 



zhread-expression &optional stream &key (completion-alist nil) (completion- 
delimiters nil) Function 

Like sys:read-for-top-level except that if it encounters a top-level end-of-file, it 
just beeps and waits for more input. This function is used by the rexpression op- 
tion for prompt-and-read. 
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stream defaults to zhstandard-input. This function is intended to read only from 
interactive streams. 

If completion-alist is not nil, this function also sets up COMPLETE and c-? as input 
editor commands. When the user presses COMPLETE, the input editor tries to com- 
plete the current symbol over the set of possibilities defined by completion-alist. 
When the user presses c-?, the input editor displays the possible completions of 
the current symbol. 

The style of completion is the same as that offered by Zwei. completion-alist can be 
nil, an alist, an sys:art-q-list array, or a keyword: 

nil No completion is offered. 

alist The car of each alist element is a string representing one pos- 

sible completion. 

array Each element is a list whose car is a string representing one 

possible completion. The array must be sorted alphabetically on 
the cars of the elements. 

keyword If the symbol is rzmacs, completion is offered over the defini- 

tions in Zmacs buffers. If the symbol is rflavors, completion is 
offered over all flavor names. If the symbol is : documentation, 
completion is offered over all documentation topics available to 
Document Examiner. 

The default for completion-alist is nil. 

completion-delimiters is nil or a list of characters that delimit "chunks" for com- 
pletion. As in Zwei, completion works by matching initial substrings of "chunks" of 
text. If completion-delimiters is nil, the entire text of the current symbol is a sin- 
gle "chunk". The default is nil. 



zhread-form &optional stream &key (edit-trivial-errors-p zh*read-form-edit-trivial- 
errors-p*) (completion-alist zh*read-form-completion-alist*) (completion-delimiters 
zh*read-form-completion-delimiters*) Function 

Like zhread-expression, but assumes that the returned value will be given imme- 
diately to eval. This function is used by the Lisp command loop and by the :eval- 
form and :eval-form-or-end options for prompt-and-read. 

stream defaults to zhstandard-input. This function is intended to read only from 
interactive streams. 

If edit-trivial-errors-p is not nil, the function checks for two kinds of errors. If a 
symbol is read, it checks whether the symbol is bound. If a list whose first ele- 
ment is a symbol is read, it checks whether the symbol has a function definition. 
If it finds an unbound symbol or undefined function, it offers to use a lookalike 
symbol in another package or calls zhparse-ferror to let the user correct the in- 
put, edit-trivial-errors-p defaults to the value of zh*read-form-edit-trivial-errors-p*. 
The default value is t. 
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If completion-alist is not nil, this function also sets up COMPLETE and c-? as input 
editor commands. When the user presses COMPLETE, the input editor tries to com- 
plete the current symbol over the set of possibilities defined by completion-alist. 
When the user presses c-?, the input editor displays the possible completions of 
the current symbol. 

The style of completion is the same as that offered by Zwei. completion-alist can be 
nil, an alist, an sys:art-q-list array, or a keyword: 

nil No completion is offered. 

alist The car of each alist element is a string representing one pos- 

sible completion. 

array Each element is a list whose car is a string representing one 

possible completion. The array must be sorted alphabetically on 
the cars of the elements. 

keyword If the symbol is rzmacs, completion is offered over the defini- 

tions in Zmacs buffers. If the symbol is rflavors, completion is 
offered over all flavor names. If the symbol is : documentation, 
completion is offered over all documentation topics available to 
Document Examiner. 

The default for completion-alist is the value of zl:*read-form-completion-alist*. 
The default value is rzmacs. 

completion-delimiters is nil or a list of characters that delimit "chunks" for com- 
pletion. As in Zwei, completion works by matching initial substrings of "chunks" of 
text. If completion-delimiters is nil, the entire text of the current symbol is a sin- 
gle "chunk". The default is the value of zl:*read-form-completion-delimiters*. The 
default value is (#\- #\: #\space). 



zl:*read-form-completion-alist* Variable 

If not nil, zl:read-form sets up COMPLETE and c-? as input editor commands. 
When the user presses COMPLETE, the input editor tries to complete the current 
symbol over the set of possibilities defined by completion-alist. When the user 
presses c-?, the input editor displays the possible completions of the current sym- 
bol. 

The style of completion is the same as that offered by Zwei. zl:*read-form- 
completion-alist* can be nil, an alist, an sys:art-q-list array, or a keyword: 

nil No completion is offered. 

alist The car of each alist element is a string representing one pos- 

sible completion. 

array Each element is a list whose car is a string representing one 

possible completion. The array must be sorted alphabetically on 
the cars of the elements. 
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keyword If the symbol is rzmacs, completion is offered over the defini- 

tions in Zmacs buffers. If the symbol is rflavors, completion is 
offered over all flavor names. If the symbol is : documentation, 
completion is offered over all documentation topics available to 
Document Examiner. 

The default value is rzmacs. 



zl:*read-form-completion-delimiters* Variable 

The value is nil or a list of characters that delimit "chunks" for completion in 
zl:read-form. As in Zwei, completion works by matching initial substrings of 
"chunks" of text. If zl:*read-form-completion-delimiters* is nil, the entire text of 
the current symbol is a single "chunk". The default value is (#\- #\: #\space). 



zl:*read-form-edit-trivial-errors-p* Variable 

If not nil, zl:read-form checks for two kinds of errors. If a symbol is read, it 
checks whether the symbol is bound. If a list whose first element is a symbol is 
read, it checks whether the symbol has a function definition. If it finds an un- 
bound symbol or undefined function, it offers to use a lookalike symbol in another 
package or calls zhparse-ferror to let the user correct the input. The default is t. 



cp:read-full-command arg-p ignore Function 

This is the n-H (extended) and colon-full-command Command Processor command 
accelerator, which lets you type extended commands to the single command accel- 
erator reader. 

cp:read-full-command is a function that is suitable for use as a command accel- 
erator's function. However, because it is already installed on ":" and n-H in the 
"Colon Full Command" command-table, the best way to make use of this facility is 
to have the command tables in your applications that use accelerator characters in- 
herit from "Colon Full Command". 

See the function cpradd-command-accelerator. For an overview of cp:read-full- 
command and related facilities: See the section "Managing Your Program Frame". 



sys:read-interval-or-never &optional stream or-nil Function 

Reads a line of input from stream (using zhreadline) and calls sirparse-interval- 
or-never on the resulting string. 



zl:readline-no-echo &optional stream &key (terminators T#\return #\line #\end)) 

(full-rubout nil) (notification t) (prompt nil) (help nil) Function 

Reads a line of input from stream without echoing the input, and returns the input 
as a string, without the terminating character. This function is used to read pass- 
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words and encryption keys. It does not use the input editor but does allow input to 
be edited using RUBOUT. 

stream must be interactive. It defaults to zl:query-io. 

Following are the permissible keywords: 



rterminators 



:full-rubout 



rnotification 



rprompt 



:help 



A list of characters that terminate the input. If the user types 
#\return, #\line, or #\end as a terminator, the function echoes 
a Newline. If the user types any other character as a termina- 
tor, the function echoes that character. The default is 
(#\return #\line #\end). 

If not nil and the user rubs out all characters on the line, the 
function returns nil. If nil and the user rubs out all characters 
on the line, the function waits for more input. The default is 
nil. 

If not nil and a notification is received, the function displays 
the notification and reprompts. If nil and a notification is re- 
ceived, the notification is ignored. The default is t. 

If nil, no prompt is displayed. Otherwise, the value should be a 
prompt option to be displayed at appropriate times. See the 
section "Displaying Prompts in the Input Editor". The default 
is nil. 

If not nil, the value should be a help option. See the section 
"Displaying Help Messages in the Input Editor". Then, when 
the user presses HELP, the function displays the help option 
and reprompts. If nil and the user presses HELP, the function 
just returns #\help. The default is nil. 



(flavorrmethod :read-location sirinteractive-stream) 



Method 



Returns the value of the scan pointer. This is also defined on noninteractive 
streams. 



zl:read-or-character &optional delimiters stream reader 



Function 



Like zhread-expression, except that if it is reading from an interactive stream 
and the user types one of the delimiters as the first character or the first charac- 
ter after only whitespace characters, it returns four values: nil, rcharacter, the 
character code of the delimiter, and any numeric argument to the delimiter. If it 
encounters any nonwhitespace characters, it calls the reader function with an argu- 
ment of stream to read the input. 

delimiters is a character, a list of characters, or nil. The default is nil. reader de- 
faults to zhread-expression. stream defaults to zhstandard-input. This function is 
intended to read only from interactive streams. 
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read-or-end &optional (stream zhstandard-input) reader Function 

Like zhread-expression except that if it is reading from an interactive stream and 
the user presses END as the first character or the first character after only whites- 
pace characters, it returns two values, nil and rend. If it encounters any non- 
whitespace characters, it calls the reader function with an argument of stream to 
read the input, reader defaults to zhread-expression. stream defaults to 
zhstandard-input. 

The :expression-or-end and :eval-form-or-end options for prompt-and-read invoke 
read-or-end. 

This function is intended to read only from interactive streams. 



dw:read-standard-token stream Function 

Parses string as delimited by activation and blip characters established by 
dw:with-accept-activation-chars and dw:with-accept-blip-chars, respectively. 

stream The input stream. 

For an overview of dw:read-standard-token and related facilities, see the section 
"Defining Your Own Presentation Types". 



rreceive-notification Message 

Sent to an interactive stream, it returns a notification when one exists in the 
stream's notification cell. The message checks the contents of the locative returned 
by the :notification-cell message to the stream. When the locative contains a noti- 
fication, rreceive-notification returns the notification and stores nil in the loca- 
tive. When the locative does not contain a notification, rreceive-notification re- 
turns nil. 



tvrrectangular-blinker Flavor 

One of the flavors of blinker provided for your use. A rectangular blinker is dis- 
played as a solid rectangle; this is the kind of blinker you see in Lisp Listeners 
and Editor windows. The width and height of the rectangle can be controlled. 



(flavorrmethod rredisplay tvrbasic-scroll-window) Method 

When a scroll window is sent the rredisplay message, it examines all parts of the 
top-level item, including all items contained in it and all items contained in them 
and so on. It adds new lines to the display as they are found, removes ones no 
longer found, and updates ones still found, that are in need of updating. 



(flavorrmethod rredisplay-variable tvrchoose-variable-values-window) variable 

Method 
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Redisplays just the value of the specified variable. 



dwrredisplayable-format stream format-string &rest format-args Function 

Outputs a formatted string redisplayably. This simply calls format within a 
caching point for incremental redisplay. (See the function dwrwith-redisplayable- 
output.) format-string is used as the cache-id; the list format-args is used as the 
cache-value. 

stream The output stream; the default is *standard-output*. 
format-string The format-control string. (See the function format.) 

format-args The format arguments. 

dwrredisplayable-format is one of a number of facilities used to do incremental 
redisplay. For examples, see the file syS:EXAMPLES;INCRemental-redisplay.lisp. 

For an overview of dwrredisplayable-format and related facilities: See the section 
"Displaying Output: Replay, Redisplay, and Formatting". 



dwrredisplayable-present object &optional presentation-type &key (stream 
*standard-output*) (unique-id nil) &allow-other-keys Function 

Presents an object redisplayably. This simply calls present within a caching point 
for incremental redisplay. (See the function dwrwith-redisplayable-output.) The 
object itself is used as the cache-value. 

object The object to present. 

presentation-type The presentation type to display the object as; the de- 

fault is the Lisp object type of the object, that is, (type-of object). 

rstream Specifies the output stream; the default is *standard-output*. 

runique-id Identifieatheparticularincrementatedisplayjache. 

This may be any object, as long as it is unique with respect to the 
id-test predicate among all such ids in the current incremental re- 
display. The default is that there is no id, not that nil is the id. 

Other keyword options to dwrredisplayable-present are the same as those to 
present, to which they are passed: See the function present. 

dwrredisplayable-present is one of a number of facilities used to do incremental 
redisplay. For examples, see the file syS:EXAMPLES;INCRemental-redisplay.lisp. 

For an overview of dwrredisplayable-present and related facilities: See the section 
"Displaying Output: Replay, Redisplay, and Formatting". 



dwrredisplayer (&optional stream) &body body Function 
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Creates a redisplay object out of its body, which can be used to do incremental re- 
display on stream. Provide the redisplay object as the redisplay-piece argument to 
dw:do-redisplay: See the function dw: do-redisplay. 

stream The output stream; the default is *standard-output*. 

dwrredisplayer is one of a number of facilities used to do incremental redisplay. 
For examples, see the file sys:EXAMPLES;INCRemental-redisplay.lisp. 

For an overview of dwrredisplayer and related facilities: See the section "Display- 
ing Output: Replay, Redisplay, and Formatting". 

Note that you cannot currently use any options with this function. 



(flavorrmethod rrefresh tvrmenu) &optional type Method 

Redraws the menu. The system sends this message with different type symbols de- 
pending on the event that caused redrawing. You can also send it; in this case the 
type argument is usually not supplied and is allowed to take on a default value. 
The menu refreshes itself from a bit-save array or redraws itself from scratch, as 
appropriate. If the bit-save array is invalid, or type is rcomplete-redisplay (this is 
the default), or the size of the menu has changed, it redraws from scratch. 



(flavorrmethod rrefresh tvrsheet) &optional type Method 

Redisplays the window. Depending on type and the existence of a bit-save array, 
clears the window or restores the image from the bit-save array. This message is 
usually sent by the system. You might need to provide an rafter daemon to recon- 
struct the contents of the window. 



(flavorrmethod rremove-asynchronous-character sirinteractive-stream) character 

Method 

Removes an asynchronous character from the list for the stream. 

See the section "Asynchronous Characters". 



(flavorrmethod rremove-highlighted-value tvrmenu-highlighting-mixin) value 

Method 

Removes an item from the list of highlighted items. Refers to the item by value. 
For instance, if your item-list is an association list, with elements (string . 
symbol), this message uses symbol. This only works for menu items that can be ex- 
ecuted without side-effects, not, for example, the reval and rfuncall kinds. 

See the section "tvrmultiple-menu-mixin Messages". 
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(flavorrmethod :replace-input sirinteractive-stream) n-chars string &optional (be- 
gin 0) end (rescan-mode rignore) Method 

Can be sent by a read function that uses the input editor to provide completion of 
the current input. 

n-chars specifies the number of characters to be removed from the end of the in- 
put buffer and erased from the screen. It can be an integer, a string, or nil: 

integer Removes n-chars characters from immediately before the scan 

pointer 

string Removes as many characters as the string contains 

nil Removes characters from the beginning of the input buffer to 

the scan pointer 

The substring of string determined by begin and end is then displayed on the 
screen, end defaults to (string-length string). The scan pointer is left after the 
string, and a rescan does not take place. If a rescan takes place at some later 
time, the characters in string are seen as input. 

rescan-mode specifies what action to take if the :replace-input message is sent 
when the scan pointer is not at the end of the input buffer: 

rignore Do not perform the rreplace-input operation. This is the de- 

fault. 

renable Perform the operation. 

rerror Signal an error. 



(flavorrmethod rreplace-item tvrtext-scroll-window) item-no new-item Method 

Replaces the item whose number is item-no with new-item. 

If the item is currently visible, the window redisplays to show the new item. 

rreprompt &rest prompt-option Option 

When it is time for the user to be reprompted, the input editor displays prompt- 
option, prompt-option can have one element, which can be nil, a string, a function, 
or a symbol other than nil; or it can have more than one element: See the section 
"Displaying Prompts in the Input Editor". 

Unlike rprompt, rreprompt displays the prompt only when input is redisplayed (for 
example, after a screen clear), not when the input editor is first entered. If both 
rprompt and rreprompt are specified, rreprompt overrides rprompt except when 
the input editor is first entered. 

(flavorrmethod rrescanning-p sirinteractive-stream) Method 
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Can be sent by a read function that uses the input editor to determine whether 
the next character returned by :tyi will come from the input buffer or from the 
keyboard. If t is returned, the input is being rescanned and the next character will 
come from the input buffer. If nil is returned, the next character will come from 
the keyboard. 



reset-user-options alist Function 

Resets each of the option variables in alist to its default initial value. 

(flavorrmethod :reverse-video-p tvrmenu) t-or-nil Init Option 

If set to t, the menu is displayed in reverse video, that is, white-on-black instead 
of black-on-white. 

(flavorrmethod :reverse-video-p tvrsheet) Method 

Returns nil normally or t if the window displays in white on black rather than 
black on white. This is separate from the whole screen's inverse video mode (set 
by FUNCTION C). 

(flavorrmethod rright tvrmenu) right-edge Init Option 

Right edge of the window specified in pixels, relative to the outside of the superior 
window. 

(flavorrmethod rright tvrsheet) right-edge Init Option 

Specifies the x-coordinate of the right edge of the window. 

(flavorrmethod rright-margin-character-flag tvrsheet) x Init Option 

If x is 1, print an exclamation point in the right margin when rend-of-line- 
exception happens; if x is 0, don't. It defaults to 0. 

(flavorrmethod rright-margin-size tvrsheet) Method 

Returns the right margin size of the window in pixels. 

(flavorrmethod rrows tvrmenu) n-rows Init Option 

Sets the number of rows. 

sysrrubout-handler Variable 
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Indicates the status of input editing within a process. 

This variable is used internally by the rinput-editor method and the input editor. 
It should not be necessary for user programs to examine its value since the with- 
input-editing special form is provided for this purpose. 

The possible values for this variable are: 

Value Meaning 

nil The process is outside the input editor. 

:read The process is inside the rinput-editor method. 

:tyi The process is inside the editing portion of the :tyi method. 



(flavorrmethod :save-bits tvrsheet) t-or-nil Init Option 

Specifies whether output to the window is written to a bit-save array when the 
window is deexposed; the default is nil. If t, the output is redisplayed following re- 
exposure of the window. The value of this option can also be rdelayed. For more 
information on bit-save arrays, see the section "Pixels and Bit-Save Arrays". 



(flavorrmethod rscreen tvrmenu) screen Init Option 

In a system with multiple screens, sets the screen on which the menu appears. 

:screen-manage-deexposed-gray-array Message 

The screen manager sends this message to deexposed windows to give them an op- 
portunity to override the kind of graying that their superior (or the screen) wants 
to provide. This message should return two values. Following are the possible 
pairs of values and their meaning: 

graying specification and nilUse graying specification to gray the window. 
nil and nil Let the superior decide how to gray the window. 

nil and t Disable graying of the window. 

See the section "Window Graying Specifications". 

tvrscreen-manage-update-permitted-windows Variable 

Controls whether the screen manager looks for partially visible windows with deex- 
posed typeout actions of rpermit and updates the visible portion of their contents 
on the screen. If the value is nil, which it is initially, the screen manager does not 
do this. Otherwise the value should be the interval between screen updates, in 
60ths of a second. 
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tv:scroll-maintain-list init-fun item-fun &optional per-element-fun stepper-fun com- 
pact-p pre-proc-fun &rest init-args Function 

Constructs and returns a list item that updates itself when the scroll window is 
asked to redisplay. Takes the following arguments: 



init-fun 

init-args 

item-fun 

per-element-fun 

stepper-fun 



compact-p 



pre-proc-fun 



The init function that will be called at redisplay time to pro- 
vide a representation of the set of objects to be displayed. 

Arguments to be passed to init-fun when called at redisplay 
time. 

The item function, to be applied to each object of yours to pro- 
duce a display item. 

A function to be put in the list item plist of the list item as 
the rfunction function. 

The function that is called on the set of objects and all "resf's 
of the set. It is expected to return three values: the next ele- 
ment, the "rest" of the set, and t if it has returned the last el- 
ement of the set. If not given, stepper-fun defaults to tvrscroll- 
maintain-list-stepper, a function that handles ordinary lists. 

An optional flag that causes tv:scroll-maintain-list to copy the 
list it builds at each redisplay into a special area for such lists, 
in order to optimize paging performance. The list so construct- 
ed will be stored in compact (that is, cdr-coded) form. 

A function to be put in the list item plist of the list item as 
the :pre-process-function function. If not given, pre-proc-fun 
defaults to tv:scroll-maintain-list-update-function. 



Following is a simple example: 

(tv:scrol 1-maintain-l ist #' (lambda (instance) ;The init function 

(send instance ' : value-1 ist)) 
#' (lambda (value) ;The item function 

(tv:scrol 1 -parse- item 

l (:string , (format nil "~S" value)))) 
nil nil nil nil 
self) ;Argument to init function 



tv:scroll-parse-item &rest line-item-spec 



Function 



Receives its arguments as a single &rest argument that is a line item spec. It con- 
structs and returns a line item. For the format of line item specs, see the section 
"Constructing Line Items". 



(flavorrmethod :scroll-to tv:basic-scroll-bar) number type 



Method 
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Scrolls the window depending on type. If type is rrelative, then scrolls the window 
number items in either the positive or negative direction. If type is rabsolute then 
puts the item whose number is number in the topmost line. 



rselect &optional (save-selected t) Message 

Sent to a selectable window by a user program or by a part of the user interface 
to change the selected activity. It is also sent by the system to notify a window 
when it becomes the selected window, either because of a change of activities or 
because of selection of this window instead of a different window within the same 
activity. 

This message is received by the system and is also received by user daemons that 
wish to be notified when a window becomes selected. 

If save-selected is not nil, the previously selected activity is saved for restoring by 
the FUNCTION S command and the rdeselect message. 

The message returns t if it works, nil if it fails. It can fail when sent to a pane if 
the rinferior-select message that the pane sends to the frame returns nil. It can 
also fail when sent to a frame that has no selected-pane. 

User programs should send the : select-relative message rather than rselect or 
rmouse-select, unless they are really responding to a user command to switch ac- 
tivities. Using : select-relative rather than rselect to change windows within an ac- 
tivity ensures that the right thing happens when that activity is not the selected 
one and avoids suddenly changing the selected activity without the consent of the 
user. 



tv:*select-keys* Variable 

As of Genera 7.3 Ivory, the SELECT key uses an internal database rather than 
tv:*select-keys*. It is retained for compatibility. 

The value of this variable is an alist, each entry of which describes a subcommand 
of the SELECT key. Entries are of the form: 

(char flavor name create-p) 

For an explanation of the components of the entries: See the function tvradd- 
select-key. Use tv:add-select-key to add a new entry or redefine an existing one 
rather than changing the value of tv:*select-keys* yourself. 



tvrselect-mixin Flavor 

Allows a window to be selectable. It provides methods for the rselect, rdeselect, 
rselect-relative, and mame-for-selection messages. 



tvrselect-or-create-window-of-flavor find-flavor &optional (create-flavor find-flavor) 

Function 
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Selects the most recently selected window of flavor find-flavor. If no window of 
that flavor exists, makes a window of flavor create-flavor and selects it. 



:select-pane pane Message 

Sent to a frame, makes pane the selected-pane of the frame, pane must be either 
an exposed inferior of the frame or nil, which means to set the selected-pane to 
nil. This message also deselects the current selected-pane if it is a window differ- 
ent from pane. Unless pane is nil, this message sends pane a : select-relative mes- 
sage. 



: select-relative Message 

Sent to a selectable window selects the window relative to its activity, but does not 
select a different activity. 

If the window that receives this message belongs to the same activity as the cur- 
rently selected window, the receiver becomes the new selected window. Otherwise, 
the window that receives this message sends the rinferior-select message to its su- 
perior to select the receiver relative to its activity. 

User programs should send the : select-relative message rather than rselect or 
rmouse-select, unless they are really responding to a user command to switch ac- 
tivities. Using : select-relative rather than rselect to change windows within an ac- 
tivity ensures that the right thing happens when that activity is not the selected 
one and avoids suddenly changing the selected activity without the consent of the 
user. 

This message returns no significant values. It is sent by the user and received by 
the system. Users should not need to define methods for it. 



tvrselect-relative-mixin Flavor 

Makes a window participate in the same activity as its superior. It provides a 
method for the :alias-for-selected-windows message that returns the window if its 
superior is a screen, or the superior's alias otherwise. It also provides a daemon 
for the rselect message that sends an rinferior-select message to the superior with 
an argument of the window. 

This flavor does not provide a method for the r select-relative message; that is 
handled by tvrselect-mixin. 



r selectable- windows Message 

Sent to a window, it returns a menu item-list of activities containing or inferior to 
the window. The mame-for-selection and ralias-for-selected-windows messages 
are used to discover the available activities. When sent to a screen, this message 
returns a menu item-list of all the activities that screen contains. 
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This message is sent by [Select] in the System menu and is received by the sys- 
tem. Users shouldn't need to send this message or to define methods for it. 



(flavorrmethod :selected-choice-style tvrbasic-choose-variable-values) character- 
style Init Option 

Specifies the character style in which the current value of a variable is displayed, 
when there is a finite set of choices. This should be a bold-face version of the pre- 
ceding character style. The default is the bold-face version of the default unselect- 
ed-choice character style. 



:selected-pane Message 

Sent to a frame, it returns the selected-pane of the frame. This message is sent by 
users and received by the system. 



(flavorrmethod :selected-pane tvrbasic-constraint-frame) pane Init Option 

Makes pane the selected-pane of this frame, pane can be the symbol used in the 
rpanes init option to name the pane. 



tv: selected- window Variable 

The value is the currently selected window. 



(flavorrmethod :send-all-exposed-panes tvrbasic-constraint-frame) message &rest 
arguments Method 

Sends the specified message with the specified arguments to all of the exposed 
panes of this frame. 



(flavorrmethod rsend-all-panes tvrbasic-constraint-frame) message &rest argu- 
ments Method 

Sends the specified message with the specified arguments to all of the panes of this 
frame, including the nonexposed ones. 



(flavorrmethod rsend-pane tvrbasic-constraint-frame) pane-name message &rest 
arguments Method 

Sends the specified message with the specified arguments to the pane that was 
named by the symbol pane-name in the rpanes specification of this frame. 



tvr sensitive-item-types Variable 
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A gettable, settable, and initable instance variable of tvrmouse-sensitive-text- 
scroll-window-without-click that controls which types of mouse-sensitive items are 
actually sensitive at any given time. 

There are several possible values for tv: sensitive-item-types: 

• t: All mouse-sensitive objects are sensitive, regardless of type. This is the de- 
fault. 

• A list: Only items whose type is an element of the list are sensitive. 

• A function: The function must take as its only argument a mouse-sensitive item 
object and it should return t if it wants the item to be sensitive and nil other- 
wise. 

• A symbol other than t: Taken to be a message to be sent to the window. The 
corresponding method should be a function of one argument returning t or nil 
as in the case of the function. 



(flavorrmethod : set-border-margin- width tv:borders-mixin) new-width Method 

Sets the value of the border margin width. 

(flavorrmethod :set-borders dwrmargin-mixin) borders Method 

Replaces the current borders of a Dynamic Window with simple borders (like those 
provided by dwrmargin-borders). 

borders The thickness, in pixels, of the new borders; the default is 1 . 

For an overview of (flavorrmethod :set-borders dwrmargin-mixin) and related fa- 
cilities: See the section "Window Substrate Facilities". 

(flavorrmethod r set-character tvrcharacter-blinker) nchar Method 

Sets the character to display to nchar. 



(flavorrmethod r set-configuration tvrbasic-constraint-frame) configuration-name 

Method 

Sets the configuration of the frame to the one named by the symbol configuration- 
name. 



(flavorrmethod r set-cur sorpos tvrblinker) x y Method 
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Sets the position of the blinker within the inside of the window. If the blinker had 
been following the cursor, it stops doing so, and stays where you put it. 



(flavorrmethod : set-cur sorpos tvrsheet) x y &optional (units 'rpixelj Method 

Moves the cursor position to the specified coordinates. The units may be specified 
as with :read-cursorpos. If the coordinates are outside the window, move the cur- 
sor position to the point nearest to the specified coordinates that is within the 
window. Sending nil for x or y leaves the current value unmodified. 



(flavorrmethod :set-deexposed-typein-action tvrsheet) action Method 

Sets the deexposed typein action of the window to action. 

(flavorrmethod rset-deexposed-typeout-action tvrsheet) action Method 

Sets the deexposed typeout action of the window to action. 

(flavorrmethod rset-default-character-style tvrmenu) new-style Method 

Changes the default character style of the menu. All items displayed in the menu 
whose character style are not otherwise specified are displayed in the default char- 
acter style. 

(flavorrmethod rset-default-character-style tvrsheet) new -default-style Method 

Changes the default character style of the window. 



dwrset-default-end-of-page-mode new -end-of -page-mode &optional new -scroll- factor 

Function 

Sets global default for what happens when queued output exceeds the space avail- 
able in the current viewport of a Dynamic Window. 

new-end-of-page-mode The new mode. There are three possibilities: 

rscroll Causes the window to scroll automatically to accommodate 
the output. If you supply this argument, make sure you 
also supply a numeric value for the new-scroll-factor argu- 
ment. 

rtruncate Causes scrolling to be the responsibility of the user, who 
must press the SCROLL key to see more output. 

rwrap Causes new output to appear at the top of the window, 
rather than at the bottom as in the case of rscroll or 
rtruncate. 
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new-scroll-factor The amount by which the window is scrolled when the 

value of the new-end-of-page-mode argument is rscroll. Permissible 
values include integers (number of lines) and ratios (fraction of the 
screen). 

For an overview of dw:set-default-end-of-page-mode and related facilities: See the 
section "Window Substrate Facilities". 



tv:set-default-window-size flavor-name superior existing-windows &rest options 

Function 

Allows you to modify the default size chosen by the system when you create a win- 
dow without specifying either a size or a position for it. For example, when you 
create a Lisp Listener by pressing SELECT c-L, the default size is the full size of 
the screen, unless you modify it. 

The arguments to tv:set-default-window-size are: 

flavor-name The flavor of window to be affected. Flavors built on top of 

this do not inherit this flavor's default window size, nil here 
means all windows. 

superior The window whose direct inferiors are to be affected; typically, 

the value of tvrmain-screen. 

existing-windows An indicator as to whether existing windows must conform to 
these options. Any non-nil argument forces all existing win- 
dows of the specified flavor-name and superior to conform to 
the options. 

options Alternating keywords and values that are used as defaults in 

creating windows whose size or position is not specified. Valid 
keywords are rwidth, :left, rright, rheight, :top, and rbottom. 
They have the same meaning as in tvrmake-window. 

For example: 

(tv : set-def aul t-wi ndow-si ze 

'zwei :zmacs-f rame tv: main-screen t ':width 1400) 



(flavorrmethod :set-deselected-visibility tvrblinker) new-visibility Method 

Changes the deselected visibility of the blinker. 

(flavorrmethod :set-display-item tvrbasic-scroll-window) item Method 

Sets the top-level item of the scroll window to item. 
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(flavorrmethod :set-edges tv:essential-set-edges) new-left new-top new-right new- 
bottom &optional option Method 

Sets the edges of the window to new-left, new-top, new-right, and new-bottom, in 
pixels, relative to the superior window, respectively. 



(flavorrmethod :set-edges tvrmenu) new-left new-top new-right new-bottom Method 

Sets the edges of the window to the four values supplied as arguments, in pixels 
relative to the superior window. 



(flavorrmethod :set-fill-p tvrmenu) t-or-nil Method 

Sets the menu's fill mode. Thus, use t to set the fill characteristic. This message 
is a special case of the rgeometryrset-geometry messages. 



(flavorrmethod rset-follow-p tvrblinker) new-follow-p Method 

Set whether the blinker follows the cursor. If this is nil, the blinker stops follow- 
ing the cursor and stays where it is until explicitly moved. Otherwise, the blinker 
starts following the cursor. 



(flavorrmethod rset-geometry tvrmenu) &optional columns rows inside-width in- 
side-height max-width max-height Method 

Takes six arguments, rather than a list of six things, as you might expect. This is 
because you frequently want to omit most of the arguments. The geometry is set 
from the arguments, which can cause the menu to change its shape and redisplay. 
An argument of nil means to make that aspect of the geometry unconstrained. An 
omitted argument or an argument of t means to leave that aspect of the geometry 
the way it is. 



(flavorrmethod rset-gray-array-for-inferiors tvrgray-deexposed-inferiors-mixin) 

gray Method 

Sets gray as the graying specification to use in graying areas of this screen or 
frame that contain no windows. See the section "Window Graying Specifications". 



(flavorrmethod rset-gray-array-for-unused-areas tvrgray-unused-areas-mixin) 

gray Method 

Sets gray as the graying specification to use in graying areas of this screen or 
frame that contain no windows. See the section "Window Graying Specifications". 



(flavorrmethod r set-half -period tvrblinker) new-half-period Method 
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Changes the half-period of the blinker. 

(flavorrmethod : set-highlighted-items tv:menu-highlighting-mixin) list Method 
Sets the list of items to be highlighted. 

(flavorrmethod : set-highlighted- values tvrmenu-highlighting-mixin) list Method 

Sets the list of items to be highlighted. Refers to the items by value. For instance, 
if your item-list is an association list, with elements (string . symbol), this message 
uses symbol. This only works for menu items that can be executed without side- 
effects, not, for example, the reval and rfuncall kinds. 

See the section "tv:multiple-menu-mixin Messages". 

(flavorrmethod : set-hysteresis tvrhysteretic-window-mixin) new-hysteresis Method 
Sets the hysteresis of the window, in pixels. 



(flavorrmethod :set-inside-size tv:essential-set-edges) new-inside-width new-inside- 
height &optional option Method 

Sets the inside width and inside height of the window to new-inside-height and 
new-inside-width, without changing the position of the upper-left corner. 



(flavorrmethod :set-io-buffer tv:command-menu) io-buffer Method 

Sets the I/O buffer to which a command-menu sends a command when an item is 
chosen. 



(flavorrmethod : set-item-list tvrmenu) list Method 

Sets the item list of a menu. 



(flavorrmethod rset-items tvrtext-scroll-window) new-items &optional (new-top-item 

0) Method 

new-items should be an array with a fill pointer. It becomes the new array used in- 
ternally to hold the list of items. The window redisplays with the item whose num- 
ber is new-top-item in the topmost line. 

new-items can also be an integer, in which case this method allocates a new array 
of that length, and set its fill pointer to zero, making the list of items empty. 



(flavorrmethod rset-label tvrlabel-mixin) specification Method 
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Changes some attributes of the label, specification can be anything accepted by the 
rlabel init option. Any attribute that specification doesn't mention retains its old 
value. 



(flavorrmethod :set-label dw:margin-mixin) label Method 

Provides a new label for a Dynamic Window. 

label The label string. 

The label can be specified with any of the options acceptable to dw:margin-mixin. 

For an overview of (flavorrmethod :set-label dwrmargin-mixin) and related facili- 
ties: See the section "Window Substrate Facilities". 

(flavorrmethod :set-label tvrmenu) label Method 

Sets the label of a menu. 

(flavorrmethod rset-location sirinteractive-stream) location Method 

Sets the value of the scan pointer. This is used for complicated parsing and for er- 
ror recovery. 

(flavorrmethod r set-margin-choices tvrmargin-choice-mixin) choices Method 

Changes the set of margin choices according to choices, which is nil to turn them 
off or a list of choice-box descriptors. If the choice boxes are turned on or off, the 
size of the window's bottom margin changes accordingly. 



(flavorrmethod r set-margin-components dwrmargin-mixin) new-components 

Method 

Replaces the current margin components of a Dynamic Window with a new set of 
components. 

new-components Specifies a list of the form ( (component-1 [_keys~\ ) 

(component-2 [_keys~\ ) ... (component-n [_keys~\ ) ) , where component-x 
is one of a set of margin-component flavors and keys are zero or 
more keywords or keyword-value pairs appropriate for the given fla- 
vor. 

For a list of available margin-component flavors and an example, 
see the flavor dwr dynamic- window. 

For an overview of (flavorrmethod r set-margin-components dwrmargin-mixin) 

and related facilities: See the section "Window Substrate Facilities". 
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(flavorrmethod :set-margin-space tv:margin-space-mixin) new-space Method 

Specifies the amount of blank space to be left in the margins of the window. Possi- 
ble values of new-space: 

nil No space 

t One pixel blank in each of the four margins 

n n pixels of space in each of the four margins (n is an integer) 

(left top right bottom) left pixels blank in the left margin, top pixels blank in 

the top margin, and so on (values are integers) 



(flavorrmethod :set-more-p tvrsheet) more-p Method 

If more-p is nil, turns off xxMorexx processing; otherwise, turns it on. 

(flavorrmethod : set-mouse-position tvressential-mouse) x y Method 

Positions the mouse blinker at window coordinates x and y. 

To position the mouse blinker at absolute screen coordinates, use the function 
tv:mouse-warp. 

For an example showing the use of : set-mouse-position, see the function 
dw:tracking-mouse. 

(flavorrmethod :set-name tv:changeable-name-mixin) new-name Method 

Set the name of the window to new-name, which should be a string. If the window 
is currently displaying the old name of the window as the label, then redraw the 
label using the new name as the text to be displayed. 

: set-notification-mode new-mode Message 

Sent to an interactive stream, sets the stream's notification mode. The notification 
mode determines what the notification delivery process does with a notification 
when the process associated with the stream does not accept it. new-mode can be a 
keyword or nil: 

:pop-up The notification is displayed in a pop-up window. This is the 

default. 

:always-pop-up Like :pop-up except that the window is not first given a choice 
of whether to accept the message. 

:blast The notification is displayed on the stream. 

rignore The notification is ignored but is added to the notification his- 

tory for SELECT N and the Show Notifications command. 
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ralways-ignore Like rignore except that the window is not first given a choice 
of whether to accept the message. 



nil The same as :pop-up. 



(flavorrmethod :set-position tv:essential-set-edges) new-x new-y &optional option 

Method 

Sets the x and y position of the upper-left corner of the window, in pixels, relative 
to the superior window, respectively. 



(flavorrmethod : set-print-function tv:function-text-scroll-window) function 

Method 

Sets the printing function of the window to function. 



(flavorrmethod :set-print-function-arg tv:function-text-scroll-window) new- 

function-arg Method 

Sets the object which the window passes as the second argument to the print 
function. 



(flavorrmethod : set-reverse- video-p tvrsheet) t-or-nil Method 

Enable or disable reverse-video display. Changing this mode inverts all of the bits 
in the window. 



tv:set-screen-background-gray gray &optional (screen tvrmain-screen) Function 

Specifies what pattern should be used to gray areas of a screen or frame that con- 
tain no windows, gray is a graying specification. See the section "Window Graying 
Specifications". Give an argument of nil to disable graying. 

screen can be a screen or frame. It defaults to the main monochrome screen. 



tv:set-screen-deexposed-gray gray &optional (screen tvrmain-screen) Function 

Specifies what pattern should be used to gray areas of a screen or frame that con- 
tain windows that are not fully exposed, gray is a graying specification. See the 
section "Window Graying Specifications". Give an argument of nil to disable gray- 
ing. 

screen can be a screen or frame. It defaults to the main monochrome screen. 



(flavorrmethod rset-sheet tvrblinker) new-window Method 
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Sets the window associated with the blinker to be new-window. If the old window 
is an ancestor or descendant of new-window, adjust the (relative) position of the 
blinker so that it does not move. Otherwise, moves it to the point (0,0). 



(flavorrmethod :set-size tv:essential-set-edges) new-width new-height &optional 
option Method 

Sets the outside width and outside height of the window to new-height and new- 
width, without changing the position of the upper-left corner. 



(flavorrmethod :set-size tvrrectangular-blinker) new-width new-height Method 

Sets the width and height of the blinker, in pixels. 



(flavorrmethod :set-size-in-characters tvrsheet) width-spec height-spec &optional 
option Method 

Sets the inside size of the window, according to the two specifications, without 
changing the position of the upper-left corner, width-spec and height-spec are inter- 
preted the same way as arguments to the rcharacter-width and rcharacter-height 
init options, respectively. 



(flavorrmethod rset-status tvressential-activate) new-status Method 

Sets the status of a window to rdeactivated, rdeexposed, rexposed, or rselected. 

timerset-local-time &optional new-time Function 

Sets the local time to new-time. If new-time is supplied, it must be either a univer- 
sal time or a suitable argument to timerparse. If it is not supplied, or if there is 
an error parsing the argument, you will be prompted for the new time. Note that 
you will not normally need to call this function; it is mainly useful when the time- 
base becomes unreliable for one reason or another. 

(flavorrmethod r set-truncate-line-out tvrsheet) new-value Method 

Sets the value of the window's truncate line out flag. If new-value is t the flag is 
turned on; if nil, it is turned off. 



(flavorrmethod r set- variables tvrchoose-variable-values-window) item-list &op- 
tional dont-set-height Method 

Changes the list of items (variables) and redisplays. Unless dont-set-height is sup- 
plied non-nil, the height of the window is adjusted according to the number of 
lines required. If more than 25. lines would be required, 25. lines are used and 
scrolling is enabled. The rsetup message uses r set- variables to do part of its work. 
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(flavorrmethod : set- viewport-position dw: dynamic- window) new-left new-top 

Method 

Scrolls the window to a specified location in the window's output history. Specify 
the location in terms of absolute window coordinates. 

new-left The x-coordinate for the viewport's left edge. 
new-top The y-coordinate for the viewport's top edge. 

For an overview of (flavorrmethod : set- viewport-position dw: dynamic- window) 

and related facilities, see the section "Presenting Formatted Output". 



(flavorrmethod : set- visibility tvrblinker) new-visibility Method 

Sets the visibility of the blinker, new-visibility should be one of :on, nil, :off, t, or 
rblink For the meaning of these values: See the section "Blinkers". 



(flavorrmethod :set-vsp tvrsheet) new-vsp Method 

Sets the value of vsp for this window to new-vsp. 



(flavorrmethod rsetup tvrchoose-variable-values-window) items label function 
margin-choices Method 

Changes the list of items (variables), the window label, the constraint function, 
and the choices in the bottom margin and sets up the display. This message re- 
members the current stack-group as the stack-group in which the variables are 
bound. If the window is not exposed this chooses a good size for it. 



(flavorrmethod rsetup tvrmultiple-choice) item-name keyword-alist finishing-choices 
item-list &optional maxlines Method 

Sets up all the various parameters of the window. Usually one sends this message 
while the window is deexposed. The window decides what size it should be and 
whether all the items will fit or scrolling is required, then draws the display into 
its bit-array. Thus, when the window is exposed, the display appears instanta- 
neously. 

For an explanation of item-name, keyword-alist, and finishing-choices, see the sec- 
tion "The Multiple Choice Facility". 

maxlines is the maximum number of lines the window can have; if there are more 
items than this only some of them are displayed and scrolling is enabled, maxlines 
defaults to 20. 



tvr sheet-following-blinker window Function 
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Takes a window and return a blinker that follows the window's cursor. If there 
isn't any, it returns nil. If there is more than one, it returns the first one it finds 
(it is pretty useless to have more than one, anyway). 



tv:sheet-force-access (sheet don't-prepare-sheet) body... Function 

Allows typeout on sheet if it has a screen array (that is, if it is exposed or has a 
bit-save array). If don't-prepare-sheet is nil, prepares the sheet before executing 
body. If sheet does not have a screen array, tv:sheet-force-access just returns 
without executing body. Use this to put output onto a deexposed window that has 
a bit- save array. 



tvrshow-partially-visible-mixin Flavor 

If a window has this flavor mixed in, the screen manager will attempt to show it 
to the user when it is partially visible even if it doesn't have a bit-save array. The 
screen manager cannot display the contents of the window, since there is no bit- 
save array to hold them, but it does give the window a screen array temporarily, 
tells it to refresh itself, and then shows whatever the window displays. Often this 
means that you will see the label and borders of the window, but no contents. 



(flavorrmethod :size tvrsheet) (outside-width outside-height) Init Option 

Specifies the outside width and height of the window. 

(flavorrmethod rsize tvrsheet) Method 

Returns two values: the outside width and outside height. 

(flavorrmethod r size-in-character s tvrsheet) Method 

Returns two values: the inside size in characters, and the inside height in lines. 
The size of the default character style is used. 

(flavorrmethod r special-choices tvrmultiple-menu-mixin) choice-list Init Option 

Each element of choice-list specifies a menu item for a multiple menu. These are 
the items that behave like normal menu items; the items from the ritem-list init 
option behave as on/off switches as described above. An element of choice-list may 
be any form of menu item. 

(flavorrmethod rstack-group tvrbasic-choose-variable-values) sg Init Option 

Specifies the stack group in which the variables whose values are to be chosen are 
bound. The window needs to know this so that it can get the values while running 
in another process, for instance the mouse process, in order to update the window 
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display when it is refreshed or scrolled. This option is required, unless you use the 
rsetup message. 



dw: standard-command-menu-handler command-name &rest args Function 

Takes command-name and arguments args as passed to the command form of a 
dw:define-command-menu-handler form, and does the standard actions for two 
mouse gestures: 

:mouse-left If the command has rconfirm arguments, read them from the 

keyboard. Otherwise, run the command with all arguments de- 
faulted. 

:mouse-right If the command has any arguments at all, read them from an 

accept-values menu. Otherwise, just run the command. 

For an overview of related topic, see the section "How Command Menus Work". 



*standard-output* Variable 

In the normal Lisp top-level loop, output is sent to whatever stream is the value of 
*standard-output*. Many input functions, including write and write-char, take a 
stream argument that defaults to *standard-output*. 

(print 'foo) = (print 'foo xstandard-outputx) 

The variable *standard-output* may be set to a file, for example, rather than an 
interactive stream, thus redirecting subsequent output to the file: 

(setq outstream 



(open "myfile" :direction :output)) 
(setq old-standard-out xstandard-outputx) 
(setq xstandard-outputx outstream) 
(print 'foo) 
(setq xstandard-outputx old-standard-out) 



opens myfile. 1 isp 

save old value 

redirects output 

prints 'foo in myfile. lisp 

restore xstandard-outputx 



It is much better, however, to use 1 et to temporarily bind the stream: 

(with-open-f ile (outstream "myfile" :direction :output) 
(let ((xstandard-outputx outstream)) ; redirects output 

(print 'foo)) ;end of let form restores 

; xstandard-outputx 
;more forms 
) ;end of with-open-f ile closes file 

By setting *standard-output* to a synonym-stream of *terminal-io*, *standard- 

output* can resume writing to the user console. 

zhstandard-output Variable 

In your new programs, we recommend that you use the variable *standard- 
output*, which is the Common Lisp equivalent of zhstandard-output. See the 
variable *standard-output*. 
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(flavorrmethod rstart-typeout sirinteractive-stream) type &optional spacing 

Method 

Informs the input editor that typeout to the window will follow. The word "type- 
out" is used in the name of this message because this is very similar to typeout in 
the editor, even though typeout windows are not actually used, type can be one of 
the following keywords: 

Keyword Action 

rinsert Typeout is inserted before the current input, as is done with 

notifications or input editor documentation. 

roverwrite Like rinsert, but the next time rinsert or roverwrite typeout is 

performed, this typeout is overwritten. 

rappend Typeout appears after the current input, which remains visible 

before the typeout. This is the style used by zlrbreak. 

rtemporary Typeout appears after the current input and is erased after the 

user types a character. 

rclear-window The window is cleared, and typeout appears at the top. 

spacing can be one of the following keywords: 

Keyword Action 

mone No spacing before typeout. 

rfresh-line Typeout begins at the beginning of a line. 

rblank-line A blank line precedes typeout. 

If spacing is not specified, a default that depends on type is computed. 

(flavorrmethod rstatus tvressential-activate) Method 

Returns one of rdeactivated, rdeexposed, rexposed, rselected, and rexposed-in- 

superior, indicating the current status of a window. 

tvrstream-mixin Flavor 

Allows a window to function as an interactive stream. It should be mixed into any 
window that can be used for interacting with a user, and particularly into any win- 
dow that can become the value of zlrterminal-io. It gives the window an I/O buf- 
fer, allows the window to handle input messages, and provides the window with in- 
put editing. 



(flavorrmethod rstring-in sirinteractive-stream) eof string &optional (start 0) end 

Method 
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Reads characters from the stream into string, using the substring delimited by 
start and end. start defaults to 0, and end defaults to the length of the string. 

eof specifies stopping actions: 

Value Action 

nil Reading characters into the string stops either when it has 

transferred the specified character count or when end-of-file is 
reached, whichever comes first. For a string with a fill pointer, 
sets the fill pointer to the location one greater than the last 
location into which a character was stored. 

not nil If end-of-file is encountered while trying to transfer a specific 

number of characters, signals sys:end-of-file, with the value of 
eof as the report string. If eof is t, a default report string is 
used. 

The method returns two values. The first is the location in the string that is one 
greater than the last one into which a character was stored. The second value is t 
if end-of-file was reached, nil otherwise. 



(flavorrmethod : string-length tvrsheet) string &optional (start 0) (end nil) (stop-x 

nil) character-style (start-x 0) (max-x 0) Method 

Like rcompute-motion, but works in only one dimension. It tells you how far the 
cursor would move if string were to be displayed in the default character style (or 
that specified by character-style) starting at the left margin, or at start-x if that is 
specified, start and end work as with :string-out to specify a substring of string. If 
stop-x is not specified or nil, the window is assumed to have infinite width; other- 
wise the simulated display will stop when a position stop-x pixels from the left 
edge is reached. 

: string-length returns three values: where the imaginary cursor ended up, the in- 
dex of the next character in the string (the length of the string if the whole 
string was processed, or the index of the character which would have moved the 
cursor past stop-x), and the maximum x-coordinate reached by the cursor (this is 
the same as the first value unless there are #/return characters in the string). 



(flavorrmethod : string-line-in sirinteractive-stream) eof string &optional (start 0) 
end Method 

A combination of :string-in and :line-in. It reads a line of characters from the 
stream into string, using the substring delimited by start and end. start defaults to 
and end to the length of string. If called from outside the input editor, reads 
characters until a #\return, #\line, or #\end activation character is encountered. If 
called from inside the input editor, reads characters until a #\return delimiter is 
encountered. The activation or delimiter character is not stored into string. 

eof specifies stopping actions: 
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Value Action 

nil Reading characters into the string stops when a delimiter is 

encountered, when the string is full, or when end-of-file is 
reached, whichever comes first. For a string with a fill pointer, 
sets the fill pointer to the location one greater than the last 
location into which a character was stored. 

not nil If end-of-file is encountered, signals sys:end-of-file, with the 

value of eof as the report string. If eof is t, a default report 
string is used. 

The method returns three values: 

• The location in string that is one greater than the last location into which a 
character was stored. 

• t if end-of-file was reached, nil otherwise. 

• nil if the entire contents of the line fit into the string or end-of-file was 
reached, otherwise t. If this value is t, as much of the line as possible was 
stored into the string and more is waiting to be read. 

If the second and third values are both nil, a delimiter was read. If either is t, no 
delimiter was read. 



(flavorrmethod :string-out tvrsheet) string &optional (start 0) (end nil) Method 

Types string on the window, starting at the character start and ending with the 
character end. If end is nil, continue to the end of the string; if neither optional 
argument is given, the entire string is typed. This behaves exactly as if each char- 
acter in the string (or the specified substring) were sent to the window with a 
:tyo message, but it is much faster. 



(flavorrmethod rstring-style tvrbasic-choose-variable-values) character-style 

Init Option 

The character style in which items that are just strings (typically heading lines) 
are displayed. The default is the system default character style. 



dwrsuggest completion-string object Function 

Adds an element to a completion table being constructed inside a dwrcompleting- 
from-suggestions macro, dwrsuggest is not used independently of this macro. 

completion-string The completion string, that is, the fully completed 

string generated from what the user typed in. 
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object The object associated with the completion string (and to be re- 
turned by dw:completing-from-suggestions). 

For an overview of dwrsuggest and related facilities, see the section "Defining 
Your Own Presentation Types". 



(flavorrmethod rsuperior tvrchoose-variable-values) window Init Option 

The argument is the window to which the pop-up choose-variable-values window 
should be inferior. The default is the value of tv:mouse-sheet, or the superior of 
w if the :near-mode option is already set to (rwindow w). 



(flavorrmethod rsuperior tvrsheet) superior Init Option 

Makes superior the superior window of the window being created. 

rsuppress-notifications flag Option 

If a notification is received while in the input editor, and flag is supplied as nil, 
the input editor itself handles the notification, regardless of any other way you 
have specified that notifications should be handled. If flag is t, notifications are 
handled in the input editor the same way they would be handled if you were not in 
the input editor. That is, the input editor does not handle the notification itself. 



surrounding-output-with-border (&optional stream &key (shape rrectangle) (thick- 
ness 1) (margin 1) (pattern t) (gray-level 1) (opaque nil) (filled nil) alu (label nil) (la- 
bel-position rbottom) (label-separator-line nil) (label-separator-line-thickness 1) (label- 
alignment rleft) (width nil) (height nil) (move-cursor t)) &body body Function 

Binds the local environment such that output generated in the body of the macro 
is enclosed within a border. The border is sized to just surround the output. 

stream The output stream; the default is *standard-output*. 

rshape Specifies the shape of theborder ; the defaultis rrectangle. Other 
possible shapes are rcircle, roval, and rdiamond. 

rthickness Specifiesthethickness,inpixels,oftheborder;thede- 

fault is 1. 

rmargin Specifiesthe minimum whitespace, in pixels, between theborder 
and the enclosed output. 

rpattern Specifies the pattern to be used in drawing the border. 
Example: 
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(defun pattern-test () 
(f resh-1 ine) 
( sur round i ng-output-wi th-border 

(xstandard-outputx : shape : rectangle 

: pattern tv:50%-gray) 
(present tv: selected-window 'tv: window))) 

If the rfilled option is t, the pattern is drawn throughout the rect- 
angular area and XORed with the unfilled values of the area's pix- 
els. 

For more information on how to specify patterns, see the section 
"Texturing". 

:gray-level Specifies the black-to-white level of the border as a ra- 

tio or decimal fraction between and 1; the default value is 1, that 
is, 100% black. This option only takes effect if you specify a 
rthickness of 1 or greater. 

ropaque A Boolean option specifying whether pixels already being displayed 
are cleared (before the border is drawn) or left alone; the default is 
t. ropaque t means draw pixels that are off in the background 
color. 



rfilled Booleanoptionspecifyingwhethertheshapedenclosedbythebor- 

der is filled; the default is nil. If t, filling occurs by XORing the 
turned-on and unfilled values of the pixels in the filled area. 

If a pattern is specified by the rpattern option, filling occurs by 
XORing the pattern values and unfilled values of the pixels. In 
general, the best results are achieved by leaving the rpattern option 
unspecified if you intend to fill. 

ralu Specifies the drawing mode for drawing drawing the border. Possi- 

ble values for this option are: 

rdraw Pixels in the border are turned on, regardless of whether 
some of the pixels were already on. This is the default 
drawing mode. 

rerase Pixels in the border are turned off, regardless of whether 
some of the pixels were already off. 

rflip Pixels in the border are turned on if they were previously 

off, and off if they were previously on. 

rlabel A string to be included within the border as a label, or a form that 
prints a label. Note that if you use a form, you must explicitly print 
the label, for example: 
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(scl :surrounding-output-with-border (nil :label (princ "ID")) 

(princ "Stuff")) 



rlabel-position Specifies the position of the label within the surround- 

ing box. The possible values are :top: put the label above the pre- 
sented output; and rbottom: put it below. In either case, the label is 
flush left with the output. 

:label-separator-line A Boolean option specifying whether to draw a line be- 
tween the label and the output. The default is nil: no line. 

:label-separator-line-thickness Specifies the thickness, in pixels, of the 

line separating the label and the output. 

rlabel-alignment Specifies how the label for the surrounding border is 

to be aligned. The possibilities are :left, rright, and reenter. 

rwidth Specifies the the maximum width, in pixels, of the border; the de- 
fault (nil) places no limit on the maximum. 

rheight Specifiesthe the maximumheight, in pixels, of theborder; the de- 
fault (nil) places no limit on the maximum. 

rmove-cursor Booleanoptionspecifyingwhetheranewlineisper- 

formed at the end of body. If this is t, the cursor is moved to posi- 
tion x = old-x-position + 0, y = old-y-position + height; if nil, then it 
is moved to x = old-x-position + width, y = old-y-position + 0. 

Example: 

(defun shape-test (shape fill-p) 
(f resh-1 ine) 

(sur round ing-output-with-border 
(xstandard-outputx : shape shape 

: filled fill-p) 
(present tv: selected-window 'tv: window))) 

To see how the differently shaped borders look, try calling the above with the vari- 
ous shape keywords. 

For an overview of surrounding-output-with-border and related facilities, see the 
section "Presenting Formatted Output". 



(flavorrmethod :tab-nchars tvrsheet) n Init Option 

n is the separation of tab stops on this window, in units of the window's char- 
width. This controls how the #\tab character prints, n defaults to 8. 
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tvrtemporary-choose-variable-values-window &optional (superior tvrmouse-sheetj 

Resource 

A resource of windows, from which tvrchoose-variable-values gets a window to 
use. 



tvrtemporary-choose-variable-values-window Flavor 

A tvrchoose-variable-values-window that is exposed temporarily. For an explana- 
tion of temporary windows, see the section "Temporary Windows". 



tvrtemporary-multiple-choice-window Flavor 

A mixture of tvrmultiple-choice and tv:temporary-window-mixin. Its behavior is 
that of a multiple-choice window that can be exposed and deexposed without deex- 
posing the windows it covers up. 



tvrtemporary-multiple-choice-window &optional (superior tvrmouse-sheetj 

Resource 

A resource of temporary multiple-choice windows. It is used by the tvrmultiple- 
choose function. 



tvrtemporary-typeout-window Flavor 

A flavor of typeout window that saves and restores the bits of its superior. When 
tv:with-terminal-io-on-typeout-window is used with a window that has this kind 
of typeout window over it, the program does not have to take any action to restore 
the display when the typeout window goes away. 



tvrtext-scroll-window Flavor 

The base flavor of text scroll window, on which all the others are built. Each item 
displays using the prinl function, truncating at the end of the line. 

tvrtext-scroll-window must be treated as a mixin. 



timertimezone-string &optional (timezone time:*timezone*) (daylight-savings-p 
(time:daylight-savings-p timertimezone)) force-numeric-p punctuate Function 

Returns the printed representation of a timezone; the default timezone is the cur- 
rent one for the user's site. The value returned is either the commonly accepted 
abbreviation for the timezone, for example, "EST" (for Eastern Standard Time); or, 
if more than one or no abbreviation is available, a signed digit string, for example, 

"-0500". 

The sign of a returned digit string indicates the location of the timezone relative 
to Greenwich; positive means east, negative west. Note that the sign of the printed 
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representation is opposite to that used internally; the printed digit string "-0500", 
for example, corresponds to an internal representation of 5.0. 

timezone A number between -12 and 12 of the form n.O or n.5. This number 
is the internal representation of the timezone whose printed repre- 
sentation is returned. Its sign is positive if you want to specify a 
timezone west of Greenwich, negative for one east of Greenwich. 
The value returned depends on the setting of the daylight-savings-p 
flag. 

daylight-savings-p Boolean option specifying whether the timezone argu- 

ment refers to the daylight-savings timezone or non-daylight-savings 
timezone. For example, supplying 5 as the timezone argument re- 
turns "EST" when daylight-savings-p is nil and "EDT" (Eastern Day- 
light Time) when it is t. 

For timezones for which straightforward rules exist governing the 
change from standard to daylight-savings time and back again, the 
timezone utility automatically switches over to the appropriate ab- 
breviation. For other timezones, the switch must be made manually. 
For more information: See the section "Specifying a Time Zone for 
Your Site". 

force-numeric-p Boolean option specifying whether to force the return 

of a signed digit string, even if a unique abbreviation is available. 

punctuate Boolean option specifying whether to insert a space at the begin- 
ning of the returned abbreviation string, for example, " EST" versus 
"EST". 



(flavorrmethod :top tvrmenu) top-edge Init Option 

Top edge of the window specified in pixels, relative to the outside of the superior 
window. 



(flavorrmethod :top tvrsheet) top-edge Init Option 

Specifies the y-coordinate of the top edge of the window. 

tv:top-box-label-mixin Flavor 

Like tv:top-label-mixin except that in addition to the label in the top margin, it 
also draws a line below the label in the top margin. If you surround the label with 
borders, then the label will appear inside a box. You have probably seen windows 
like this appear as momentary menus, with a prompt at the top in a box. 

(flavorrmethod :top-item tvrtext-scroll-window) Method 
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Returns the number of the item being displayed in the topmost line of the window, 
or zero if the item list is empty. 



tv:top-label-mixin Flavor 

Like tv:label-mixin except that the label is placed at the top of the window by de- 
fault, instead of the bottom. 



(flavorrmethod :top-margin-size tvrsheet) Method 

Returns the top margin size of the window in pixels. 

dw:tracking-mouse f&optional stream &key (swhostate "Track Mouse",) :who-line- 
documentation-string :who-line-more-documentation-string .-multiple-window) &body 
clauses Function 

Tracks the mouse in the user process. User-supplied routines are executed when 
mouse events occur, such as position changes and the pressing or releasing of a 
button. Note that, of the options listed here, there are two groups whose use is 
mutually exclusive: the presentation set, including rpresentation, rpresentation- 
hold, and :presentation-click; and the mouse-motion set, including rmouse-motion, 
:mouse-motion-hold, and :mouse-click. Use of the presentation set is preferred. 
Also note that presentation can be nil sometimes. 

stream The output stream; the default is *standard-output*. 

rwhostate Specifiesthestringdisplayedintherun-stateslotof 

the status line. The default value is "Track Mouse". 

:who-line-documentation-string Specifiesthemousedocumentation 
string. 

rmultiple-window All functions are called with their x and y coordinates 

relative to the window. This allows you to track the mouse across 
different panes. 

clauses Keyword-value pairs supplying routines (the values) executed when 
the mouse event indicated by the keyword occurs. Some keywords 
provide arguments. Available keywords and their arguments are de- 
scribed below: 

rpresentation (presentation) Smallest presentation under 

mouse, or nil; called when the mouse moves. 

:presentation-hold (presentation) Same as rpresentation, but 

used if a mouse button is still down. 

rmouse-motion (x y) Position of the mouse; called when the 

mouse moves. 
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rmouse-motion-feedback (x y) 

:mouse-motion-hold (x y) Same as rmouse-motion, but used if a 
mouse button is still down. 

:who-line-documentation-string () Allows dynamic control of 

mouse documentation line; called whenever anything 
changes. 

:release-mouse () Called when all mouse buttons are up af- 

ter some were down. 

rkeyboard {char) Called when user presses a keyboard key 

(rather than clicking). 

:presentation-click {mouse-char presentation) Called when 

a mouse button is pressed, presentation is the smallest 
presentation under mouse, or nil; mouse-char is the 
mouse-character object corresponding to the mouse ges- 
ture used. 

:mouse-click {mouse-char x y) Called when a mouse but- 

ton is pressed. Arguments are the mouse position and the 
mouse-character object corresponding to the mouse ges- 
ture used. 

To see the macro in action, try the following example: 

To run this function create two lisp listeners side by side. 
In the first Lisp Listener type the form: 

(setq *LL1x xterminal -iox) . 
Click left on the second Lisp Listener and enter the form: 

(mouse-1 xterminal-iox) . 

(defvar *LL1x) 
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(defun mouse-1 (window) 
(dw: tracking-mouse (window) 
( :who-l ine-documentation-string 



(if (zerop (tv: mouse-buttons)) 
"Buttons up" 
"Buttons Down")) 
(: release-mouse () 

(format *LL1x "~&Mouse key released")) 
(: mouse-motion (x y) 

(format *LL1x "~&Mouse motion(~d,~d) " x y)) 
( :mouse-motion-hold (x y) 

(format *LL1x "~&Mouse motion hold(~d,~d)" x y)) 
( :mouse-cl ick (button x y) 
(graphics:draw-rectangle x y (+ x 10) (+ y 10)) 
(selector button char-mouse-equal 
(#\mouse-left (format *LL1* "~&Left click")) 
(#\mouse-middl e-2 
(return-from mouse-1 "~&That's All Folks! ")))))) 

Here is another example, showing how you can effect "rubber-banding" while draw- 
ing a line. 
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(defun input-a-line () 
(multiple-value-bind (start-x start-y) 
(dw : track i ng-mouse 
(t :whostate "Pick starting point" 

:who-l ine-documentation-string "Put start of line here.") 
( :mouse-cl ick (click x y) 
(unless (eql click #\mouse-l) 

(signal 'sys: abort)) 
(return (values x y)))) 
(let ((old-x nil) (old-y nil)) 
(dw : wi th-output-recordi ng-di sabl ed 



(dw: tracking-mouse (t :whostate "Pick end point" 

:who-l ine-documentation-string 
"Put other end of line here.") 
(: mouse-motion (x y) 
(when (and old-x old-y) 

(graphics:draw-l ine start-x start-y old-x old-y :alu :flip)) 
(graphics:draw-l ine start-x start-y x y :alu :flip) 
(setq old-x x old-y y)) 
( :mouse-cl ick (click x y) 
(unless (eql click #\mouse-l) 

(signal 'sys: abort)) 
(when (and old-x old-y) 

(graphics:draw-l ine start-x start-y old-x old-y :alu :flip)) 
(return (values start-x start-y x y) ))))))) 

(defun input-a-line () 

(multiple-value-bind (start-x start-y) 
(dw: tracking-mouse 

(t :whostate "Pick starting point" 

:who-l ine-documentation-string "Put start of line here.") 
( :mouse-cl ick (click x y) 
(unless (eql click #\mouse-l) 

(signal 'sys: abort)) 
(return (values x y)))) 
(dw: tracking-mouse (t :whostate "Pick end point" 

:who-l ine-documentation-string 

"Put other end of line here.") 
(: mouse-motion-feedback (x y) 

(graphics:draw-l ine start-x start-y x y :alu :flip)) 
( :mouse-cl ick (click x y) 
(unless (eql click #\mouse-l) 

(signal 'sys: abort)) 
(return (values start-x start-y x y)))))) 

This last example shows the use of still lower-level facilities, such as the messages 
(flavorrmethod rvisible-cursorpos-limits dw: dynamic- window) and 

(flavorrmethod : set-mouse-position tv:essential-mouse) to monitor and control 
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the position of the mouse cursor, rvisible-cursorpos-limits is needed because 
dw:tracking-mouse provides the mouse cursor position in terms of absolute win- 
dow coordinates. Therefore, cursor positioning and output operations performed in 
conjuction with dw:tracking-mouse must also use absolute window coordinates. 

(defun line-art () 

;; Get the limits of the current window viewport 
;; in absolute window coordinates 
(multiple-value-bind (x1 y1 x2 y2) 

(send xstandard-outputx : visible-cursorpos-1 imits) 
(ignore x2 y2) 

;; Move mouse cursor to relative window 
; ; coordinates (200 200) 
(send xstandard-outputx : set-mouse-position 

(+ x1 200) (+ y1 200)) 
(dw: tracking-mouse (t) 

;; Draw lines from cursor to relative (200 200) 
(: mouse-motion (x y) 

(graphics:draw-line (+ x1 200) (+ y1 200) x y)) 
( :mouse-cl ick (button x y) 
(ignore x y) 

;; When Mouse-M is clicked, exit and leave 
;; mouse cursor at relative (0 200) 
(if (char-mouse-equal button #\mouse-m) 
(return-from line-art 
(values 

(send xstandard-outputx : set-mouse-position 

(+ x1 0) (+ y1 200)) 
(values)))))))) 

For an overview of dw:tracking-mouse and related facilities, see the section "Pro- 
gramming the Mouse: Writing Mouse Handlers". 



tv:truncatable-lines-mixin Flavor 

If you mix in this flavor and the window's truncate line out flag is on, typeout does 
not wrap around when lines are too long. That is, when the cursor is near the 
right-hand edge of the window and an attempt is made to type out a character, the 
character is not typed out; text is truncated at the edge of the window. When the 
truncate line out flag is turned off, this flavor has no effect. 



(flavorrmethod :truncate-line-out tvrsheet) Method 

Returns t if the window's truncate line out flag is set, or nil if it is not. 

tv:truncating-lines-mixin Flavor 
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When this flavor is mixed in, lines of output that are too long to fit inside the 
window do not wrap around but are truncated at the edge of the window. This fla- 
vor is built on tv:truncatable-lines-mixin. It initializes the window's truncate line 
out flag to be on. 



tvrtruncating-window Flavor 

Built on tvrwindow with tv:truncating-lines-mixin mixed in. If you instantiate a 
window of this flavor, it will be like regular windows of flavor tvrwindow except 
that lines will be truncated instead of wrapping around. 



cp:turn-command-into-form command arguments Function 

Translates a Command Processor command into an evaluable form by quoting non- 
self-evaluating elements of arguments. 

command The command. 

arguments The arguments to the command. 

For an overview of cp:turn-command-into-form and related facilities: See the sec- 
tion "Managing Your Program Frame". 



tv:turn-off-sheet-blinkers window Function 

Sets the visibility of all blinkers on window to :off. 

(flavorrmethod :tyi sirinteractive-stream) &optional eof-action Method 

If called from outside the input editor, this is the same as :any-tyi, except that 
only integers and nil can be returned. Blips are discarded, unless the first element 
of the blip is rmouse-button and the second element is #\Mouse-R; in this case, 
the method pops up a system menu. If called from inside the input editor with 
:full-rubout specified and if an activation blip is read when the input buffer is 
empty, the method causes control to be returned from the input editor. 

(flavorrmethod :tyi-no-hang sirinteractive-stream) &optional eof-action Method 

Like :any-tyi-no-hang, except that only integers and nil can be returned. Blips are 
discarded, unless the first element of the blip is rmouse-button and the second el- 
ement is #\Mouse-R; in this case, the method pops up a system menu. 

(flavorrmethod rtyo tvrsheet) ch Method 

Type ch on the window, as described in "How Windows Display Characters". Basi- 
cally, type the character ch in the current font at the cursor position, and advance 
the cursor position. 
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sir*typeout-default* Variable 

A keyword that determines how the Command Processor prints help messages. 
Possible values are those acceptable as the first argument to the rstart-typeout 
message to interactive streams: 

rinsert The help message, like a notification, is inserted before the 

current input. 

roverwrite The help message is inserted before the current input, but the 

next time an rinsert or roverwrite operation is done, this mes- 
sage is overwritten. This is the default. 

rappend The help message appears after the current input, which is 

reprinted after the help message. 

rtemporary The help message appears after the current input and disap- 

pears when you type the next character. 

rclear-window The window is cleared and the help message appears at the 

top. 

For more information: See the method (flavorrmethod rstart-typeout 
sirinteractive-stream). 



(flavorrmethod rtypeout-window tvressential-window-with-typeout-mixin) (flavor- 
name . options) Init Option 

Provides a typeout window inferior to the window, flavor-name is the flavor of 
typeout window to create; options are options to tvrmake-window. You can set to 
nil to suppress the typeout window. 



tvrtypeout-window Flavor 

Standard flavor of typeout window. 

tvrtypeout-window-with-mouse-sensitive-items Flavor 

A typeout window with tvrbasic-mouse-sensitive-items mixed in. 

tvrunexpected-select-delay Variable 

The amount of time, in sixtieths of a second, that a user is given to notice a pop- 
up notification and stop typing. Until that time has elapsed, all typein is directed 
to the previously selected window. During this time the user can press RBORT to 
deexpose the pop-up window. A value of nil means no delay time and no display of 
the message that typing any character deexposes the pop-up window. Default: 180. 
(three seconds). 
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cprunparse-command command-name arguments &optional (command-table 
cp:*command-table*) (acceptably t) Function 

Returns the input string corresponding to a Command Processor command and its 
arguments. (The string is created via a call to present-to-string.) 

command-name The command name (symbol). 

arguments The list of command arguments. 

command-table The command table containing the named command; 

the default is the current command table. 

acceptably Boolean argument passed through to present-to-string and speci- 
fying whether the output string can subsequently be parsed by 
accept and used for input. 

For an overview of cprunparse-command and related facilities: See the section 
"Managing Your Program Frame". 



dw:unread-char-for-accept char stream Function 

Puts a character back into the input stream. This character will be the next one 
read by a subsequent call to dw:read-char-for-accept. 

char The character. 

stream The input stream. 

For an overview of dw:unread-char-for-accept and related facilities, see the sec- 
tion "Defining Your Own Presentation Types". 



(flavorrmethod :unselected-choice-style tvrbasic-choose-variable-values) charac- 
ter-style Init Option 

Determines the character style in which choices for a value, other than the cur- 
rent value, are displayed. The default is a small distinctive character style. 



(flavorrmethod runtyi sirinteractive-stream) ch Method 

Returns ch to the input buffer or the stream so that it will be the next character 
returned by :any-tyi or :tyi. ch must be the last character that was rtyi'ed, and it 
is illegal to do two runtyi's in a row. Where ch is put depends on the value of the 
variable sysrrubout-handler. Following is a summary of actions for each possible 
value of sysrrubout-handler: 

nil If the input buffer contains scanned input, decrement the scan 

pointer. Otherwise, give ch back to the stream. 

rread Decrement the input editor scan pointer. 

:tyi Give ch back to the stream. 
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This method is used by parsers that look ahead one character, such as zlrread. 

(flavorrmethod runtyi tv:stream-mixin) ch Method 

Return ch to the proper buffer so that it will be the next character returned by 
:any-tyi or :tyi. ch must be the last character that was rtyi'ed, and it is illegal to 
do two runtyi's in a row. Where ch is put depends on the value of the variable 
sysrrubout-handler. Following is a summary of actions for each possible value of 
sysrrubout-handler: 

nil If the input buffer contains scanned input, decrements the scan 

pointer. Otherwise, puts ch back into the window's I/O buffer. 

:read Decrements the input editor scan pointer. 

:tyi Puts ch back into the window's I/O buffer. 

This method is used by parsers that look ahead one character, such as zhread. 

(flavorrmethod :update-item-list tv:dynamic-...-menu) Method 

Updates the item list if it needs to change; this message is accepted by menus 
with the dynamic item-list mixin. The :update-item-list message sends a rset-item- 
list if one is necessary. The dynamic menu sends itself this message automatically 
at appropriate times. The appropriate times are before rchoose, rmove-near- 
window, rcenter-around, :size, and :pane-size messages. 

(flavorrmethod rupdate-label dwrmargin-mixin) Method 

Causes a new label to be written for a Dynamic Window. The label must have pre- 
viously been created via the :delayed-set-label method: See the method 
(flavorrmethod :delayed-set-label dwrmargin-mixin). 

For an overview of (flavorrmethod rupdate-label dwrmargin-mixin) and related 
facilities: See the section "Window Substrate Facilities". 



(flavorrmethod rvalue-style tvrbasic-choose-variable-values) character-style 

Init Option 

The character style in which values of variables are displayed. The default is the 
system default character style. 



(flavorrmethod rvariables tvrbasic-choose-variable-values) item-list Init Option 

Specifies the list of variables whose values are to be chosen. These can be either 
symbols that are variables, or the more general items defined previously, see the 
section "Variables and Types". 
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time:verify-date day month year day-of-the-week Function 

Returns nil if the day of the week of the date specified by day, month, and year is 
the same as day-of-the-week; otherwise, returns a string that contains a suitable er- 
ror message, year can be absolute or relative to 1900 (that is, 84 and 1984 both 
work). 



(flavorrmethod rvisible-cursorpos-limits dw: dynamic- window) &optional {unit 
rpixel) Method 

Returns the left, top, right, and bottom limits of the current viewport. The limits 
are returned as absolute window locations. 

unit The unit of measure for the viewport limits; the default is rpixel. 

The alternative is rcharacter. The character used is the space char- 
acter in the window's default character style. 

For an example showing the use of rvisible-cursorpos-limits, see the function 
dwrtracking-mouse. 

For an overview of (flavorrmethod rvisible-cursorpos-limits dwr dynamic- window) 

and related facilities, see the section "Presenting Formatted Output". 



(flavorrmethod rupdate-label tvrdelayed-redisplay-label-mixin) Method 

Actually does the rset-label operation on the specification given by the most recent 
rdelayed-set-label message. 



(flavorrmethod rvisibility tvrblinker) symbol Init Option 

Sets the initial visibility of the blinker. This defaults to rblink. 

(flavorrmethod rvsp tvrmenu) n-pixels Init Option 

Sets the vertical spacing between lines in the menu. The default is 2 pixels. 

(flavorrmethod rvsp tvrsheet) n-pixels Init Option 

Initializes the window's vsp. It defaults to 2. The vsp is the space between lines: 
below the lowest descender and above the highest ascender. 

(flavorrmethod rvsp tvrsheet) Method 

Returns the value of vsp for this window. 

tvrwait-for-mouse-button-down &optional (prompt "Button") Function 
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If any buttons are down, waits until all the buttons are up, then waits for any 
mouse button to be pushed. If no buttons are down, waits for any button to be 
pushed, prompt is the whostate to display while waiting. Returns the same three 
values as tv:mouse-wait. 

This must be called inside a tv:with-mouse-and-buttons-grabbed or a tvrwith- 
mouse-and-buttons-grabbed-on-sheet form. 



tv:wait-for-mouse-button-up &optional (prompt "Release Button") (timeout nil) 

Function 

Waits until all mouse buttons are up, or until timeout sixtieths of a second have 
elapsed, prompt is the whostate to display while waiting. Returns the same three 
values as tv:mouse-wait. 

This must be called inside a tv:with-mouse-and-buttons-grabbed or a tvrwith- 
mouse-and-buttons-grabbed-on-sheet form. 



(flavorrmethod :who-line-documentation-string tvrsheet) Method 

The Scheduler periodically sends this message to the window owning the mouse. 
The returned value is displayed in the mouse documentation line. The value should 
be a string or, for no documentation, nil. This method returns nil; supply your 
own to provide mouse documentation. You can supply two values to obtain two 
lines of documentation. 



tv: *who-line-f unction-hook* Variable 

Allows you to add your own functions to display things in the progress note area 
of the status line. You set this variable to a function. The function is called in sev- 
eral places in the rupdate routine. 

Note: Only one function is allowed and the variable must be reset when the hook 
function is changed. 



tv:who-line-mouse-grabbed-documentation Variable 

When grabbing or usurping the mouse, you should explain what is going on in the 
mouse documentation line at the bottom of the screen. tv:with-mouse-grabbed and 
tv:with-mouse-usurped bind this variable to nil, which makes the mouse documen- 
tation line blank. Inside the body of one of these special forms, you can setq this 
variable to a string to be displayed in the mouse documentation line. If your pro- 
gram has "modes" that affect how the click acts, each part of the program should 
setq this variable to its own documentation. 



tv:who-line-mouse-grabbed-more-documentation Variable 
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The value is the string displayed as the message in the second (lower) mouse doc- 
umentation line when the mouse has been grabbed (as within a tvrwith-mouse- 
grabbed). Inside the body of tv:with-mouse-grabbed or tv:with-mouse-usurped, 
you should setq this variable to an appropriate string. See the variable tvrwho- 
line-mouse-grabbed-documentation. 



(flavorrmethod rwidth tvrchoose-variable-values) arg Init Option 

Specifies how wide to make the window. This can be a number of characters, or a 
string (it is made just wide enough to display that string). The default is to make 
it wide enough to display the current values of all the variables, provided that is 
not too wide to fit in the superior window. 



(flavorrmethod rwidth tvrmenu) arg Init Option 

Specifies the width of the window in pixels. 

(flavorrmethod rwidth tvrrectangular-blinker) n-pixels Init Option 

Sets the initial width of the blinker, in pixels. By default, it is set to the width of 
a space character in the default character style of the window associated with the 
blinker. 

(flavorrmethod rwidth tvrsheet) outside-width Init Option 

Specifies the outside width of the window. 



tvrwindow-call (window &optional final-action &rest final-action-args) &body body 

Function 

Temporarily selects a window — selecting a new activity if the window is not part 
of the currently selected activity — executes the body, then (in an 
unwind-protect) usually restores the previously selected activity. The previously 
selected activity is not restored if at that time the selected window is not window 
or a direct or indirect inferior of it. This heuristic deals with the case where the 
user has switched activities explicitly during the execution of body. 

This uses the rselect message but is different from using the save-selected and re- 
store-selected arguments to rselect and rdeselect: tvrwindow-call restores the activ- 
ity that was current when its execution began, not the second most recently select- 
ed activity, as sending a rdeselect message with an argument of t would. 

window is a variable that is bound to the window to be selected. If final-action is 
specified, it is a message to be sent to window when done with it, and final-action- 
args are forms supplying arguments to that message, final-action is often 
rdeactivate. 
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tv:window-call-relative is preferred over tv:window-call for use by application 
programs that are not responding to an explicit user command to switch activities. 



tv:window-call-relative (window &optional final-action &rest final-action-args) 
&body body Function 

Temporarily selects a window relative to its activity, executes the body, then (in 
an unwind-protect) restores the previous selected-pane of that activity. This uses 
the : select-relative message. 

window is a variable that is bound to the window to be selected. If final-action is 
specified, it is a message to be sent to window when done with it, and final-action- 
args are forms supplying arguments to that message, final-action is often 
rdeactivate. 

tv:window-call-relative is preferred over tv:window-call for use by application 
programs that are not responding to an explicit user command to switch activities. 



tv:window-hacking-menu-mixin Flavor 

Provides for the :window-op item type. The window that the menu is exposed over 
is remembered. The remembered window is used if an item of type :window-op is 
selected. See the section "Types of Menu Items". 



tv:window-mouse-call (window &optional final-action &rest final-action-args) 
&body body Function 

Similar to tv:window-call but uses rmouse-select instead of rselect to select win- 
dow. It is used by parts of the user interface that want the temporary- window- 
clearing features of rmouse-select. 



tv:window-pane Flavor 

An instantiable flavor that includes tvrpane-mixin and tvrwindow. 

tv:window-with-typeout-mixin Flavor 

Flavor to mix into a superior window to provide an inferior typeout window. 



dw:with-accept-activation-chars (additional-characters &key override) &body body 

Function 

Binds local environment to establish additional characters to be used as delimiters 
of input strings. Predefined activation characters are #\Return and #\End. 

additional-characters A list of characters to be used as additional delimiters. 
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roverride Boolean option specifying whether the characters provided in the 
additional-characters argument are the only delimiters used within 
the body of the macro. If t, the provided characters replace the ex- 
isting set for the dynamic extent of the macro. The default is nil, 
meaning that the supplied characters are added to the existing set 
of delimiters. 

For an overview of dw:with-accept-activation-chars and related facilities, see the 
section "Defining Your Own Presentation Types". 



dw:with-accept-blip-chars (additional-characters &key override) &body body 

Function 

Binds local environment to establish additional characters to be used as delimiters 
of input blips. The characters are additional only if a previous, higher-level call to 
this macro in a nested structure has established an existing set of delimiters; no 
predefined set exists. 

additional-characters A list of characters to be used as additional delimiters. 

roverride Boolean option specifying whether the characters provided in the 
additional-characters argument are the only delimiters used within 
the body of the macro. If t, the provided characters replace the ex- 
isting set for the dynamic extent of the macro. The default is nil, 
meaning that the supplied characters are added to the existing set 
of delimiters. 

For an overview of dw:with-accept-blip-chars and related facilities, see the sec- 
tion "Defining Your Own Presentation Types". 



dw:with-accept-help options &body body Function 

Binds local environment to control HELP-key documentation for input to accept. 

options A list of option specifications. Each specification is itself a list of 
the form (<help-option> <help-string>) . 

help-option The help-type or a list of the form (<help-type> <mode- 
flag>). Help types are: 

:top-level-help Specifies that help-string be used instead 
of the default help documentation provided by 
accept. 

rsubhelp Specifies that help-string be used in addition to 
the default help documentation provided by 
accept. 

Available modes include: 
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rappend Specifies that the current help string be append- 
ed to any previous help strings of this type (top- 
level help or subhelp). This is the default mode. 

roverride Specifies that the current help string is the help 
for this help type; no lower-level calls to 
dw:with-accept-help can override this. 
(roverride works from the outside in.) 

restablish-unless-overridden Specifies that the current 
help string be the help text for this help unless 
a higher-level call to dw:with-accept-help has 
already established a help string for this help 
type in the roverride mode. 

help-string A string or a function returning a string. If a function, 
it receives two arguments, the stream and the string-so- 
far. 

Examples: 

(dw:with-accept-help ((:subhelp "This is a test.")) 
(accept 'pathname)) 

==> You are being asked to enter a pathname. [ACCEPT did this] 
This is a test. [You did this] 

Use c-? or c-/ for a list of possibil ities. [Completer did this] 

(dw:with-accept-help ((: top-level -help "This is a test.")) 
(accept 'pathname)) 

==> This is a test. [You did this] 

Use c-? or c-/ for a list of possibil ities. [Completer did this] 

(dw:with-accept-help (((:subhelp :override) "This is a test.")) 
(accept 'pathname)) 

==> You are being asked to enter a pathname. [ACCEPT did this] 
This is a test. [You did this] 

[Completer did 
nothing because 
you overrode it] 

(def ine-presentati on-type test () 
: parser ((stream) 

(values (dw:with-accept-help 

((:subhelp "A test is made up of three things:")) 
(dw:completing-f rom-suggestions . . .))))) 
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(accept 'test) ==> You are being asked to enter a test. 
A test is made up of three things: 

;;;use function to provide help string 
(dw:with-accept-help (((: top-level -help :override) 

(lambda (stream string-so-far) 
(format stream "You are typing 

a pathname")))) 
....) 

For an overview of dw:with-accept-help and related facilities, see the section 
"Defining Your Own Presentation Types". 



dw:with-accept-help-if cond options &body body Function 

Conditionally binds local environment to control HELP-key documentation for input 
to accept. Similar to dw:with-accept-help, but conditional. 

cond The condition. 

options A list of option specifications. Each specification is itself a list of 
the form (<help-option> <help-string>) . 

help-option The help-type or a list of the form (<help-type> <mode- 
flag>). Help types are: 

:top-level-help Specifies that help-string be used instead 
of the default help documentation provided by 
accept. 

rsubhelp Specifies that help-string be used in addition to 
the default help documentation provided by 
accept. 

Available modes include: 

rappend Specifies that the current help string be append- 
ed to any previous help strings of this type (top- 
level help or subhelp). This is the default mode. 

roverride Specifies that the current help string is the help 
for this help type; no lower-level calls to 
dw:with-accept-help can override this. 
(roverride works from the outside in.) 

restablish-unless-overridden Specifies that the current 
help string be the help text for this help unless 
a higher-level call to dw:with-accept-help has 
already established a help string for this help 
type in the roverride mode. 
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help-string A string or a function returning a string. If a function, 
it receives two arguments, the stream and the string-so- 
far. 

This macro is equivalent to the following form: 

( i f <cond> 

(dw:with-accept-help <> body) 
body) 

For examples, see the dictionary entry for dw:with-accept-help. 

For an overview of dw:with-accept-help-if and related facilities, see the section 
"Defining Your Own Presentation Types". 



with-character-face (face &optional (stream t) &key bind-line-height) &body body 

Function 

Binds the local environment such that character output is in the specified face. 

face The face to be used for character output, for example, :bold or 

ritalic. 

stream Output stream; the default is *standard-output*. 

:bind-line-height Boolean option specifying whether the height, in pixels, 

of the line containing the character output is based on the size of 
the default character style or of the style specified in the macro. 
Whether you specify t or nil (the default) depends on the context of 
the output. To see the difference, run the following function first 
with nil, then with t (put the code in an editor buffer first and 
change the fonts of the strings to nil.): 

(defun line-height-binder (bind) 
(format t "~&First line") 
(format t "~&Foo") 

(with-character-style ('(:fix : roman :very-large) t 
:bind-l ine-height bind) 
(write-string "bar")) 
(write-string "baz") 
(terpri) 

(write-string "Another string") 

(with-character-style ('(:fix : roman :very-large) t 
: bi nd-1 ine-height bind) 
(format t "~&Frob one~%Frob two~%")) 
(format t "Last line")) 

In this example, the difference is apparent though subtle; even 
more subtle are the differences produced when only the character 
family or face is changed, as opposed to its size. 
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The height of the default character style is determined from the 
height of the space character. 

To see a list of valid character style faces, evaluate the variable si:*valid-faces*. 
For more information on character styles, see the section "Character Styles". 

For an overview of with-character-face and related facilities, see the section 
"Character Environment Facilities". 



with-character-family (family &optional (stream t) &key bind-line-height) &body 
body Function 

Binds the local environment such that character output is in the specified family. 

style The family to be used for character output, for example, rserif or 

:jess. 

stream Output stream; the default is *standard-output*. 

:bind-line-height Boolean option specifying whether the height, in pixels, 

of the line containing the character output is based on the size of 
the default character style or of the style specified in the macro. 
Whether you specify t or nil (the default) depends on the context of 
the output. To see the difference, run the following function first 
with nil, then with t (put the code in an editor buffer first and 
change the fonts of the strings to nil.): 

(defun line-height-binder (bind) 
(format t "~&First line") 
(format t "~&Foo") 

(with-character-style ('(:fix : roman :very-large) t 
:bind-l ine-height bind) 
(write-string "bar")) 
(write-string "baz") 
(terpri) 

(write-string "Another string") 

(with-character-style ('(:fix : roman :very-large) t 
: bi nd-1 ine-height bind) 
(format t "~&Frob one~%Frob two~%")) 
(format t "Last line")) 

In this example, the difference is apparent though subtle; even 
more subtle are the differences produced when only the character 
family or face is changed, as opposed to its size. 

The height of the default character style is determined from the 
height of the space character. 

To see a list of valid character style families, evaluate the variable si:*valid- 
families*. For more information on character styles, see the section "Character 
Styles". 
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For an overview of with-character-family and related facilities, see the section 
"Character Environment Facilities". 



with-character-size (size &optional (stream t) &key bind-line-height) &body body 

Function 

Binds the local environment such that character output is of the specified size. 

size The size of character output, for example, :very-small or :very- 

large. 

stream Output stream; the default is *standard-output*. 

:bind-line-height Boolean option specifying whether the height, in pixels, 

of the line containing the character output is based on the size of 
the default character style or of the style specified in the macro. 
Whether you specify t or nil (the default) depends on the context of 
the output. To see the difference, run the following function first 
with nil, then with t (put the code in an editor buffer first and 
change the fonts of the strings to nil.): 

(defun line-height-binder (bind) 
(format t "~&First line") 
(format t "~&Foo") 

(with-character-style ('(:fix : roman :very-large) t 
:bind-l ine-height bind) 
(write-string "bar")) 
(write-string "baz") 
(terpri) 

(write-string "Another string") 

(with-character-style ('(:fix : roman :very-large) t 
: bi nd-1 ine-height bind) 
(format t "~&Frob one~%Frob two~%")) 
(format t "Last line")) 

In this example, the difference is apparent though subtle; even 
more subtle are the differences produced when only the character 
family or face is changed, as opposed to its size. 

The height of the default character style is determined from the 
height of the space character. 

To see a list of valid character style sizes, evaluate the variable si:*valid-sizes*. 
For more information on character styles, see the section "Character Styles". 

For an overview of with-character-size and related facilities, see the section 
"Character Environment Facilities". 



with-character-style (style &optional (stream t) &key bind-line-height) &body body 

Function 
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Binds the local environment such that character output is in the specified style. 

style List of the form (.-family :face .size) specifying character style. 

stream Output stream; the default is *standard-output*. 

:bind-line-height Boolean option specifying whether the height, in pixels, 

of the line containing the character output is based on the size of 
the default character style or of the style specified in the macro. 
Whether you specify t or nil (the default) depends on the context of 
the output. To see the difference, run the following function first 
with nil, then with t (put the code in an editor buffer first and 
change the fonts of the strings to nil.): 

(defun line-height-binder (bind) 
(format t "~&First line") 
(format t "~&Foo") 

(with-character-style ('(:fix : roman :very-large) t 
:bind-l ine-height bind) 
(write-string "bar")) 
(write-string "baz") 
(terpri) 

(write-string "Another string") 

(with-character-style ('(:fix : roman :very-large) t 
: bi nd-1 ine-height bind) 
(format t "~&Frob one~%Frob two~%")) 
(format t "Last line")) 

In this example, the difference is apparent though subtle; even 
more subtle are the differences produced when only the character 
family or face is changed, as opposed to its size. 

The height of the default character style is determined from the 
height of the space character. 

A character style specifies three style components: family, face, and size. To see 
lists of valid families, faces, and sizes, evaluate the variables si:*valid-families*, 
si:*valid-faces*, and si:*valid-sizes*. (The same information is presented in anoth- 
er section; see the section "Available Character Styles".) Note that not all permuta- 
tions of family, face, and size are legitimate character styles. 

A partially specified character style is merged against the default character style 
for the window. (See the init option (flavorrmethod :default-character-style 
tvrsheet) and see the section "Merging Character Styles".) Consider the following 
example (which has to be compiled): 

(defun character-style-merge () 
(dw:with-own-coordinates (t) 

(with-character-style ('(nil :bold :large) t) 
(graphics:draw-string "CURRENT DATA" 100 100 

:alu :flip)))) 
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The character style specification in the above example only specifies two compo- 
nents, face and size. The nil supplied in the family component slot means that the 
default family for the window is used. If you wish to keep the defaults for two of 
the components, then you can use one of the following macros: 

with-character-family 

with-character-face 

with-character-size 

You can determine the character style corresponding to a particular TV font by us- 
ing the si:backtranslate-font function. (See the function si:backtranslate-font.) 

Example: 

(si :backtranslate-font ' fonts :bigfnt) 

#<CHARACTER-STYLE FIX. ROMAN . VERY-LARGE 260250707> 

tf<STANDARD-CHARACTER-SET 260000540> 



#<B&W-SCREEN-DI SPLAY-DEVICE 260302767> 

The example shows that fontsrbigfnt corresponds to the (:fix :roman :very-large) 

character style. 

For more information on character styles, see the section "Character Styles". 

For an overview of with-character-style and related facilities, see the section 
"Controlling Character Style". 



with-input-editing (&optional stream keyword) &body body Function 

Provides a convenient way of invoking the input editor for use by a reading func- 
tion. It establishes a context in which input editing should be provided. Use with- 
input-editing instead of sending an rinput-editor message directly. 

Both "arguments" are optional, stream is the stream from which characters are 
read; if stream is not provided or is nil, *standard-input* is used. 

keyword determines the activation characters for the input editor: 

Value Activation characters 

nil None (unless specified at a higher level). This is the default. 

:end-activation #\end 

:line-activation #\end, #\return, and #\line 

:line #\end, #\return, and #\line. In addition, a Newline is echoed af- 

ter the reading function returns. 

To supply other input editor options: See the function with-input-editing-options. 
See the function with-input-editing-options-if. 
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with-input-editing defines an internal lexical closure with body as its body. When 
the with-input-editing form is evaluated from outside the input editor, the stream 
is sent an rinput-editor message if it handles it. The argument to the rinput- 
editor message is the lexical closure, except that if the :line keyword is supplied, 
with-input-editing also arranges to echo a Newline after the lexical closure re- 
turns. If the with-input-editing form is evaluated from inside the input editor or 
if the stream does not handle the rinput-editor message, the lexical closure is 
called instead. 

with-input-editing returns whatever values body returns. 

The following example defines a simple sentence parser. 

(defun read-sentence (&optional (stream cl :*standard-inputx)) 
(with-input-edi ting-options ((:prompt "Type a sentence: ")) 
(with-input-editing (stream) 
(loop named sentence 

with sentence = nil 

for word = (make-array 20. :type art-string : f il 1-pointer 0) 
do (loop for char = (send stream :tyi) 
do 
(cond ((memq char ' (#\space #\return #\. #\? #\,)) 
(if (not (equal word "")) 
(push word sentence)) 
(selectq char 

((tf\space #\return #\,) 
(return)) 

(tfV 
(push :period sentence) 
(return-from sentence (nreverse sentence))) 

(ft\? 
(push : question-mark sentence) 
(return-from sentence (nreverse sentence))))) 
(t (array-push-extend word char)))))))) 

For an overview of this and related functions: See the section "Invoking the Input 
Editor". 



Provides a convenient way of invoking the input editor for use by a reading 
function, and establishes a context in which input editing should be provided. 

Both "arguments" are optional, stream is the stream from which characters are 
read; if stream is not provided or is nil, xterminal-iox is used. 

keyword is reserved for future use. 

with-input-editing returns whatever values body returns. 



with-input-editing-options options &body body Function 

Specifies input editing options and executes body with those options in effect. The 
scope of the option specifications is dynamic. 
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options is a list of input editor option specifications. Each element is a list whose 
car is an option-name specification and whose cdr is a list of forms to be evaluated 
to yield "arguments" for the option. The option-name specification is a keyword 
symbol or a list whose car is a keyword symbol. The symbol is the name of the 
option. 

If the option-name specification is a list and if the symbol roverride is an element 
of the cdr of the list, this option specification overrides any higher-level specifica- 
tions for this option. Otherwise, the specification for each option that is dynamical- 
ly outermost (that is, the specification from the highest-level caller) is in effect 
during the execution of body. 

with-input-editing-options returns whatever values body returns. 

In the following example, the user is prompted for a Lisp expression. Two input 
editor options are specified. The first says that the caller is also willing to receive 
mouse or menu blips. The second specifies a prompt. 

(with-input-editing-options (( :preemptable :blip) 

(: prompt "Form: ")) 
(read)) 

In the following example, the user is prompted for a line of text. The text may be 
activated by any of the characters RETURN, END, or TRIRNGLE. This might be useful 
if activating with TRIRNGLE meant something different from activating with 
RETURN. This example also demonstrates the use of roverride to make this 
ractivation specification override any higher-level ractivation specifications. 

(with-input-editing-options 

((( :activation :override) 'memq ' (#\return #\end #\triangle))) 
(prompt-and-read :string "Name: ")) 

For an overview of this and related functions: See the section "Invoking the Input 
Editor" 

For a list of input editor options: See the section "Input Editor Options". See the 
function with-input-editing-options-if. 

In the following example, the user is prompted for a Lisp expression. One input 
editor option is specified, and that option specifies a prompt. 

(with-input-editing-options (((:prompt :override) "Form: ")) 
(read)) 

To write a reading function that invokes the input editor, you should use the with- 
input-editing macro. 



with-input-editing-options-if cond options &body body Function 

Executes body, possibly with specified input editing options in effect. The scope of 
the option specifications is dynamic. 

cond is a form to be evaluated at run-time. If cond returns non-nil, the specified 
input editor options are in effect during the execution of body. 
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options is a list of input editor option specifications. Each element is a list whose 
car is an option-name specification and whose cdr is a list of forms to be evaluated 
to yield "arguments" for the option. The option-name specification is a keyword 
symbol or a list whose car is a keyword symbol. The symbol is the name of the 
option. 

If the option-name specification is a list and if the symbol roverride is an element 
of the cdr of the list, this option specification overrides any higher-level specifica- 
tions for this option. Otherwise, the specification for each option that is dynamical- 
ly outermost (that is, the specification from the highest-level caller) is in effect 
during the execution of body. 

with-input-editing-options-if returns whatever values body returns. 

For an overview of this and related forms: 

See the section "Invoking the Input Editor". 

For a list of input editor options: See the section "Input Editor Options". See the 
function with-input-editing-options. 

tv:with-mouse-and-buttons-grabbed &body body Function 

The forms in body are evaluated with the mouse and buttons grabbed. When the 
buttons are grabbed, the mouse process does not maintain the value of tvrmouse- 
last-buttons. Instead, the user process can read directly from the mouse buttons, 
without losing clicks that the mouse process might fail to notice. Within the body 
of this form, you can call the functions tv:mouse-wait, tv:wait-for-mouse-button- 
down, tv:wait-for-mouse-button-up, and sysrmouse-buttons. 



tv:with-mouse-and-buttons-grabbed-on-sheet (&optional (sheet 'self)) &body body 

Function 

Like tv:with-mouse-and-buttons-grabbed, except that the mouse is confined to 
sheet. During execution the variables sys:mouse-x and sys:mouse-y are relative to 
the window's outside coordinates. The default value of sheet is self, so if sheet is 
not supplied, this form needs to appear inside a method or defun-method of a win- 
dow flavor. 



tv:with-mouse-grabbed Function 

A tv:with-mouse-grabbed special form has only a body: 

(tv : wi th-mouse-grabbed 
forml 
form2) 

The forms inside are evaluated with the mouse grabbed. 
tv:with-mouse-grabbed-on-sheet (&optional (sheet 'self)) &body body Function 
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Evaluates body with the mouse grabbed and confined to sheet. During execution 
the variables sys:mouse-x and sys:mouse-y are relative to the window's outside 
coordinates. The default value of sheet is self, so if sheet is not supplied, this form 
needs to appear inside a method or defun-method of a window flavor. 



tv:with-mouse-usurped Function 

A tv:with-mouse-usurped special form has just a body: 
(tv : wi th-mouse-usurped 
forml 
form2) 

The forms inside are evaluated with the mouse usurped. The system does not han- 
dle mouse moves at all when the mouse is usurped; it does not even maintain the 
mouse x-y position. 

tv:with-notification-mode {new-mode &optional stream) &body body Function 

Executes body with the notification mode of stream bound to new-mode, stream de- 
faults to zhstandard-output. The notification mode determines what the notifica- 
tion delivery process does with a notification when the process associated with 
stream doesn't accept it. new-mode can be a keyword or nil: 

:pop-up The notification is displayed in a pop-up window. This is the 

default. 

rblast The notification is displayed on the stream. 

rignore The notification is ignored but is added to the notification his- 

tory for SELECT N and the Show Notifications command. 

nil The same as :pop-up. 



dw:with-output-as-presentation (&key stream object type form location single-box 
(allow-sensitive-inferiors t)) &body body Function 

Outputs an object as a presentation object; in effect, allows you to rewrite the 
printer function (used locally) for a presentation type. The following example illus- 
trates this point: 

(defun present-this-as-that (this that 

&optional (stream xstandard-outputx)) 
(send stream : clear-history) 

(dw:with-output-as-presentation (: single-box t 
:stream stream :type that :object this) 
(send stream :draw-ci rcle 250 200 25) 
(send stream :draw-ci rcle 270 200 25))) 
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Try calling this function with "ABC" as the first argument and 'string as the sec- 
ond. Now, do (accept 'string) and click on the graphic. 

Note the : single-box t option used in the above example. This is nearly always 
appropriate when using this macro for graphic presentations. 

Following are the keyword arguments recognized by dwrwith-output-as- 
presentation. Note that some of them are required. 

rstream Specifies stream on which the object is presented; the default is 
*standard-output*. 

robject Specifies the presentation object of the output presentation. If you 
do not use this option, then you must supply either the :form or 
rlocation option. 

:type Specifies the type of the presentation. You must provide this option. 

:form Specifies a form that can be passed to setf to store a new value in 
place of the current output value. This option and rlocation are mu- 
tually exclusive. 

The form supplied for this option is used by a predefined, side- 
effecting mouse handler (available on c-n-Right) to modify the con- 
tents of structure slots. 

rlocation Specifies a locative that can be used to store a new value in place 
of the current output value. This option and rform are mutually ex- 
clusive. 

The locative supplied for this option is used by a predefined, side- 
effecting mouse handler (available on c-n-Right) to modify the con- 
tents of structure slots. 

rsingle-box Specifies that mouse-sensitivity of objects output in a 

series of inferior calls to this form be indicated by a single, large 
box for highlighting rather than the sum of all the individual boxes. 
This option is used mostly with graphic presentations. 

rallow-sensitive-inferiors Boolean option specifying whether nested 

calls to present or dwrwith-output-as-presentation from inside this 
presentation — for example, when presenting the individual ele- 
ments of a Lisp list — generate presentation objects. The default is 
t. 

Example: 
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(defun sensitive-inferior-test (sensitive-p) 
(let ((fl 'dw: dynamic-window)) 
(dw : wi th-output-as-presentati on 
(: object fl 
:type 'sys: flavor-name 
:al low-sensitive- inferiors sensitive-p) 
(format t "The flavor ~S." fl)))) 

Try calling sensitive-inferiors-test with t, then nil. You should 
find that in the first case both the entire presentation and the fla- 
vor name are individually sensitive depending on where you have 
the mouse cursor; in the latter case, only the entire presentation is 
sensitive. 

For an overview of dw:with-output-as-presentation and related facilities; See the 
section "Using Presentation Types for Output". 



(flavorrmethod :with-output-recording-disabled dw: dynamic- window) continua- 
tion xstream Method 

Disables output recording on a specified window for a specified continuation. 

continuation The continuation, a function of one argument, the out- 

put stream. 

xstream The window whose output recording is disabled. 

Example: 

(defun draw-circles (stream) 
(loop repeat 50 
do 
(graphics :draw-ci rcle 
(random 500) 
(random 500) 10 : stream stream))) 

(send xstandard-outputx 

: wi th-output-recordi ng-di sabl ed 
tf'draw-ci rcles xterminal-iox) 

See also the macros, dwrwith-output-recording-disabled and dwrwith-output- 
recording-enabled. 



dw:with-output-to-presentation-recording-string (stream) &body body Function 

Binds the local environment to output to a string, the way with-output-to-string 
does, except that the string records presentations resulting from calls to present 
and dw:with-output-as-presentation. If the resulting string is subsequently print- 
ed (via princ or present) to a stream supporting presentations, the recorded pre- 
sentations are re-presented to that stream. 
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stream The output stream; the default is *standard-output*. 

dw:with-output-to-presentation-recording-string is distinguished from present-to- 
string as follows: 

w-o-to-p-r-string present-to-string 

Returns a presentation-recording string Returns an ordinary string 
Arbitrary body writing to string Single object to be presented 

Example: 

(defun test-pr-string () 

(let ((string (dw:with-output-to-presentati on-recording-string 
(xstandard-outputx) 

(dolist (symbol '(butcher baker candlestick-maker)) 
(write-string " ") 
(present symbol 'symbol))))) 
(princ string) 
(accept 'symbol))) 

For an overview of dw:with-output-to-presentation-recording-string and related 
facilities: See the section "Displaying Output: Replay, Redisplay, and Formatting". 



dwrwith-output-truncation (&optional stream &rest options) &body body Function 

Binds the local environment to allow textual output to extend beyond the bottom 
and right borders of the output window. 

stream The output stream; the default is *standard-output*. 

To access text extending beyond the margins of the output window, 
the window needs vertical and horizontal scroll bars. For informa- 
tion on how to equip Dynamic Windows with scroll bars (and other 
margin components), see the flavor dw: dynamic- window. 

options Two options are available: 

rhorizontal Boolean option specifying whether truncation occurs in 
the horizontal dimension. If you do not specify any option, 
they both default to t. If you specify either rhorizontal or 
rvertical to be t, then the other option defaults to nil. 

"Truncation" here means that output exceeding the width 
of the window extends beyond the right margin of the 
current window viewport; the margin truncates the user's 
view of the output. If nil, the output wraps to the next 
line. 

rvertical Boolean option specifying whether truncation occurs in 
the vertical dimension. The default, when neither option 
is specified, is t, meaning that output exceeding the 
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height of the window extends below the bottom margin of 
the current window viewport. If you specify either 
rhorizontal or rvertical to be t, then the other option de- 
faults to nil. 

Example: 

(defun truncation-test (t-or-nil) 

(dw: :with-output-truncation (t :horizontal t-or-nil) 
(loop repeat 100 do (write-char #\a)))) 

For an overview of dwrwith-output-truncation and related facilities, see the sec- 
tion "Presenting Formatted Output". 



dw:with-own-coordinates (&optional stream &key left top right bottom (clear- 
window t) (erase-window nil) (enable-output-recording t)) &body body Function 

Binds the local environment such that output to a Dynamic Window is in a re- 
freshed area, and the coordinate system is relative to the current viewport, not the 
window's origin. 

dw:with-own-coordinates is only appropriate when you are dealing with absolute 
constant coordinates. If you are doing anything relative, it is not for you. All mes- 
sages like :read-cursorpos and rmouse-position deal in plane coordinates. If you 
are doing anything relative to those values, the right thing will happen. Do not be 
put off by the fact that the y coordinates keep getting larger as the history gets 
longer — big numbers are nothing to be afraid of. 

Examples: 

A valid use: 

(dw:with-own-coordinates () 

(graphics:draw-circle 100 100 100)) 

Some things that do not require it. 

Cursor relative graphics block: 

(graphics: with- room-for-graphics () 

(graphics:draw-triangle 200 150 45)) 

Mouse relative graphics: 

(tracking-mouse line drawing example above) 

stream The output stream; the default is *standard-output*. 

:left Specifiesthex-coordinateatthebeginningoftheareatobeerased 

when the rerase-window option is t. 

:top Specifiesthey-coordinateatthebeginningoftheareatobeerased 

when the rerase-window option is t. 
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rright Specifies the x-coordinate at the end of the area to be erased when 
the rerase-window option is t. 

rbottom Specifiesthey-coordinateatthe end of the areatobe erased when 
the rerase-window option is t. 

rclear-window Boolean option specifying whether the window is 

scrolled to a clear area before output begins; the default is t. 

rerase-window Booleanoptionspecifyingthattheoutputwindowbe 

erased before output begins; the default is nil. 

If this option is t, use the rleft, rtop, rright, and rbottom keywords 
to specify the coordinates of the area to be erased. If no coordinates 
are specified, they default to the coordinates of the current view- 
port. Output begins at the top of the erased area. 

renable-output-recording BoolearaptioiBpecifyinTghetheautput 

is retained in the output history of the window; the default is t. 

This option is useful with animated graphic presentations that, be- 
cause of the time required for redisplay, can impede scrolling 
through a window's history. 



dwrwith-presentation-input-context (presentation-type &rest options) (&optional 
(blip-var 'dwrr.blip.)) non-blip-form &body blip-cases Function 

Binds local environment to the input context of a specified presentation type. (This 
essentially establishes mouse sensitivity for that type, and is one of the building 
blocks for accept.) The body (non-blip-form) is executed. If no mouse gestures are 
made by the user during execution of the body, this form returns the value of the 
non-blip- form. If the user clicks on a presentation of an appropriate type, the cor- 
responding blip-cases form is executed, with the resulting presentation blip bound 
as the value of blip-var. 

presentation-type The presentation type establishing the new input con- 

text. This may be a compound type incorporating more than one 
primitive type. 

options Two predefined keyword options are available: 

rstream Specifies the input stream; the default is *standard- 
input*. 

rinherit Boolean option specifying whether to inherit an existing 
input context or to establish a new root node; the default 
is t. 

You may use any additional keywords you want. 
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blip-var The symbol to bind to the blip generated by clicking on an object of 
the specified type while in the context. 

non-blip-form The body form to execute inside the established input 

context. 

blip-cases A case statement clause list. The keys are presentation types. The 
clause whose key matches the presentation type of the blip is exe- 
cuted, with the blip-var bound to the blip. 

The presentation types available for use as keys are limited to the 
type specified by the presentation-type argument or, in the case of a 
compound presentation type (for example, or), the types specified; 
and the type or types inherited in the case of a nested use of this 
macro. 

For an overview of dw:with-presentation-input-context and related facilities: See 
the section "Presentation Input Context Facilities". 



dw:with-presentation-input-editor-context (stream presentation-type options) 

(&optional (blip-var 'dw::.blip.) start-loc-var) non-blip-form &body blip-cases 

Function 

Establishes an input context around a call to the input editor to read keyboard in- 
put from the user. The body (non-blip-form) is executed. If no mouse gestures are 
made by the user during execution of the body, this form returns the value of the 
non-blip- form. If the user clicks on a presentation of an appropriate type, the re- 
sulting presentation blip is bound as the value of blip-var; the current location in 
the input buffer is bound as the value of start-loc-var; and the corresponding blip- 
cases form is executed. 

accept uses this mechanism to establish an input context for the presentation type 
being read. This is one of the substrate functions used to build accept. Most pro- 
grams simply want to call accept, instead of working at this low level. 

stream The input stream; the default is *standard-input*. 

presentation-type The presentation type establishing the new input con- 

text. This may be a compound type incorporating more than one 
primitive type. 

options One predefined keyword option is available: 

rinherit Boolean option specifying whether to inherit an existing 
input context or to establish a new root node; the default 
is t. 

You may use any additional keywords you want. 

blip-var The symbol to bind to the blip generated by clicking on an object of 
the specified type while in the context. 
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start-loc-var The symbol to bind to the input buffer location at the 

time the presentation blip is received. 

non-blip-form The body form to execute inside the established input 

context. 

blip-cases A case statement clause list. The keys are presentation types. The 
clause whose key matches the presentation type of the blip is exe- 
cuted, with the blip-var bound to the blip. 

The presentation types available for use as keys are limited to the 
type specified by the presentation-type argument or, in the case of a 
compound presentation type (for example, or), the types specified; 
and the type or types inherited in the case of a nested use of this 
macro. 

This macro is built on dw:with-presentation-input-context, to which it is similar: 

(dw:with-presentation-input-edi tor-context (stream type) 

(bl ip-var) 
body-form 
bl ip-clauses) 

is the same as 

(with-input-editing (stream) 

(dw : wi th-presentati on-i nput-context 
(type : stream stream) 
(bl ip-var) 

body-form 
bl ip-clauses)) 

For an overview of dw:with-presentation-input-editor-context and related facili- 
ties: See the section "Presentation Input Context Facilities". 



dw:with-presentation-type-arguments (type-name type) &body body Function 

Binds local environment such that the arguments in a presentation-type specifica- 
tion are lexically available within the body of the macro. 

type-name The name of the presentation type whose arguments are to be used, 
for example, pathname. 

type The type specification, for example, '((pathname) : format : directo- 

ry :direction :write). 

The type-name argument is known at compile time. It fixes the template for decod- 
ing the arguments of the particular type specification passed to the macro at run- 
time. 

Example: 
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(def ine-presentati on-type wood ((&key tree grade) 

&key show-price) 
: printer ((wood stream &key type) 

(format stream "~A [wood ~h, ~A~:[~; ~2D cents"]]" 
wood tree grade show-price 

(compute-wood-price type)))) 

(defun compute-wood-price (presentation-type) 

(dw:with-presentati on-type-arguments (wood presentation-type) 
(let ((base-price 

(ecase tree 
(mahogany 69) 
(pine 12) 
(teak 75))) 
(grade-mul tipl ier 
(ecase grade 
(f i rsts-and-seconds 1.3) 
(firewood .2)))) 
(x base-price grade-multiplier)))) 

(compute-wood-price '((wood :tree teak : grade firewood) 

:show-price t)) ==> 
15.0 

See the section "Defining Your Own Presentation Types". 

For an overview of dw:with-presentation-type-arguments and related facilities, 
see dw:with-type-decoded. 



dwrwith-redisplayable-output (&key stream cache-value unique-id (cache-test #'eql) 
copy-cache-value (id-test #'eql) ) &body body 

Function 

Introduces a caching point for incremental redisplay. If this is used outside the dy- 
namic scope of an incremental redisplay, it has no particular effect. However, 
when incremental redisplay is occurring, the supplied cache-value is compared with 
the value stored in the cache identified by unique-id. If the values differ, the code 
in body runs, and cache-value is saved for next time. If the cache values are the 
same, the code in body is not run, because the current output is still valid. 

rstream Specifies the output stream; the default is *standard-output*. 

:cache-value Specifiesthevaluetobecomparedeachtimeagainst 

the value stored in the cache. 

:unique-id Identifieatheparticularincrementatedisplayjache. 

This may be any object, as long as it is unique with respect to the 
id-test predicate among all such ids in the current incremental re- 
display. The default is that there is no id, not that nil is the id. 
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:cache-test Specifiesthetestusedtocomparecac/ie-uaZueagainst 

the value saved in the cache. The default is eql. 

:copy-cache-value Boolean optionspecifyingwhethertocopy-seqthe 

cache value before saving it in the cache. Use this, for example, 
when the cache value is a stack list which must be copied before 
being stored away somewhere. 

:id-test Specifies the testused to locate the cache identifiedby unique-id 

among the caches used by the current incremental redisplay. The 
default is eql. 

dwrwith-redisplayable-output is one of a number of facilities used to do incre- 
mental redisplay. For examples, see the file 

SYS EXAMPLES ;INCREMENTAL-REDISPLAY .LISP. 

For an overview of dwrwith-redisplayable-output and related facilities: See the 
section "Displaying Output: Replay, Redisplay, and Formatting". 



dwrwith-replayable-output (&rest parameters) &body body Function 

Binds the local environment such that all of the output generated by body becomes 
a single, replayable presentation. 

The code in body is snapshotted (using dwrnamed-value-snapshot-continuation) 
so that it can be rerun (replayed) in an altered environment; this results in a new 
printed representation. The user specifies the new output parameters at runtime 
via the Edit Viewspecs mouse handler. This handler is invoked by clicking 
s-sh-Middle on a replayable presentation. 

parameters A list of variable specifications in the style of 

dwraccept-variable-values. That is, each item in the list is a list of 
the form (variable-name prompt-string presentation-type) . 

The parameters are used to construct an dwraccept-variable-values 
menu which pops up in response to the mouse gesture Edit 
Viewspecs (s-sh-Middle). The values of the variables then be 
changed by the user, and the presentation rerun with the new val- 
ues. 

Example: 



Page 1431 



; ; ; Compile and run this code, then Edit Viewspecs by 
; ; ; clicking s-sh-Middle on its output. 

(defun wrpo () 
(f resh-1 ine) 

(let ((style '(:fix : roman : normal)) 
(width 50) 
(start 1)) 
(dw : wi th-repl ayabl e-output 

((style "Character style" character-style) 
(width "Width in characters" ((integer 5 120))) 
(start "Starting from" integer)) 
(with-character-style (style) 
(let ((fill-width 

(* width (send xstandard-outputx :char-width)))) 
(filling-output (() :fill-column fill-width) 
(loop repeat 50 

for i from start 

do (format T " ~r" i)))))))) 

dwrwith-replayable-output is similar to dw:with-output-as-presentation in the 

sense that it lets you define a presentation-type printer "on the fly", that is, not as 
part of a presentation type. In the case of dwrwith-replayable-output, you are 
writing a printer that can be modified by the user at runtime, via the Edit 
Viewspecs handler. This is not the only way to provide users with the ability to al- 
ter displayed presentations; you can use the rviewspec-choices option to define- 
presentation-type to provide the same capability with regard to all presentations 
of the defined type. See the section "rviewspec-choices Option to define- 
presentation-type " . 

dwrwith-resortable-output is a specialization of dwrwith-replayable-output for re- 
ordering and redisplaying lists: See the function dwrwith-resortable-output. 

For an overview of dwrwith-replayable-output and related facilities: See the sec- 
tion "Displaying Output: Replay, Redisplay, and Formatting". 



dwrwith-resortable-output ((list key &key copy-of) &rest sort-clauses) other- 
parameters &body body Function 

Binds the local environment such that all of the output generated by body becomes 
a single, replayable presentation. The list can be output in one of several orders 
specified by sorting predicates. Which sorting predicate is used can be specified by 
users at runtime via the Edit Viewspecs mouse handler, available on s-sh-Middle. 

list A variable holding the sequence of items for output. 

key A variable holding an identifier for selecting which of the sort- 

clauses is used. 
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:copy-of Specifies a list to be copied and sorted instead of list. The value is 
copied by copy-seq. Typically, the value of this option is list. Use it 
when you do not want the order of the original list to be destroyed 
by sorting. 

sort-clauses An ecase body, selecting on sort keys (the value of 

key), and returning a sort predicate. 

other-parameters Other parameters included in the parameters argument 

passed to dwrwith-replay able-output: See the function dwrwith- 
replayable-output. These and the sorting options appear in the 
dw: accept- variable- values display created by the Edit Viewspecs 
handler. 

To see this macro in action, execute the Command Processor command Show Pro- 
cesses or Show Directory. Both use dwrwith-resortable-output and produce output 
resortable via the Edit Viewspecs handler (s-sh-Middle). 

Another example: 

(defun sortable-output () 
(let ((data (make-array 10)) 
(how : alpha) 

(style '(:swiss nil nil))) 
(dotimes (i 10) 

(setf (aref data i) 

(list i (format nil "~r" i)))) 
(dw : wi th-resortabl e-output 
; ; 1 ist and key 
((data how) 
; ; sort clauses 
( : alpha 

(lambda (x y) 

(string-lessp (second x) (second y)))) 
( : length 

(lambda (x y) 

(< (string-length (second x)) 
(string-length (second y))))) 
( : number 

(lambda (x y) 

(< (first x) (first y))))) 
; ; other parameter 

((style "Character style" character-style)) 
; ; body 
(with-character-style (style) 

(format t "~&Here come the data, sorted by ~(~a~): " how) 
(format-textual -1 ist data 

(lambda (x stream) 

(princ (second x) stream))))))) 
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For an overview of dwrwith-resortable-output and related facilities: See the sec- 
tion "Displaying Output: Replay, Redisplay, and Formatting". 



tv:with-terminal-io-on-typeout-window (window wait-for-space-p) &body body 

Function 

Binds zl:terminal-io to the typeout-window of window over the duration of the 
body, taking care of exposing and deexposing the typeout window, selection, etc. 
wait-for-space-p, if supplied and not nil, means that after executing the body the 
user should be prompted to type a space to get rid of the typeout window. Other- 
wise the typeout window goes away as soon as the body returns. All values of the 
body are returned. 



dw:with-type-decoded (type-name-var &optional data-args-var presentation-args-var) 
type &body body Function 

Binds local environment such that the type-name and, optionally, arguments in a 
presentation-type specification are bound to variables lexically available within the 
body of the macro. 

type-name-var Symbol to bind the type-name of the presentation type. 

data-args-var Symbol to bind to a list of the data arguments of the 

presentation type. 

presentation-args-var Symbol to bind to a list of the presentation arguments 
of the presentation type. 

Example: 

(defun with-type-decoded-test () 

(dw:with-type-decoded (type-name data-args pres-args) 

' ((integer 1 10) :base 8 

: description "Integer between 1 and 10") 
(format t "~2%Type: ~A 

~%Data Arguments: ~A 
~%Presentation Arguments: ~A" 
type-name data-args pres-args))) 

(with-type-args-test) ==> 

Type: INTEGER 

Data Arguments: (1 10) 

Presentation Arguments: (BASE 8 DESCRIPTION Integer between 1 and 10) 

See the section "Defining Your Own Presentation Types". 
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For an overview of dw:with-type-decoded and related facilities: See also: dwrwith- 
presentation-type-arguments. 



with-underlining (&optional stream &key (underline-whitespace t)) &body body 

Function 

Binds the local environment such that character output is underlined. 

stream Output stream; the default is *standard-output*. 

runderline-whitespaceBoolearoptiorBpecifyingvhethewhitespacaainder- 

lined (in addition to characters); the default is t. If the output you 
are underlining contains any newline characters, we recommend 
that you set this option to nil. 

Example: 

(defun underline-example () 
(f resh-1 ine) 
(with-underlining () 

(princ 12345) 

(sleep 2) 

(princ 56789))) 

For an overview of with-underlining and related facilities: see the section "Con- 
trolling Line Output". 



(flavorrmethod :x tvrmenu) arg Init Option 

Specifies the left edge of the menu in pixels, relative to the outside of the superior 
window. 



(flavorrmethod :x tvrsheet) left-edge Init Option 

Specifies the x-coordinate of the left edge of the window. 

(flavorrmethod :x-pos tvrblinker) x Init Option 

Along with the :y-pos init option, sets the initial position of the blinker within the 
window. This init option is irrelevant for blinkers that follow the cursor. The ini- 
tial position for nonfollowing blinkers defaults to the current cursor position. 

(flavorrmethod :x-scroll-position dw: dynamic- window) Method 

Returns four values: 

1. The absolute location of the current viewport's left edge. 
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2. The viewport's horizontal extent. 

3. The window's minimum x-coordinate (typically 0). 

4. The absolute location of the viewport's right edge. 

For an overview of (flavorrmethod :x-scroll-position dw: dynamic- window) and re- 
lated facilities, see the section "Presenting Formatted Output". 

(flavorrmethod :x-scroll-to dw: dynamic- window) position type Method 

Scrolls the window to a specified x-coordinate. 

position The x-coordinate to scroll to. 

type The type of scrolling operation. Three possibilities exist: 

rabsolute The position argument specifies an absolute window loca- 
tion. 

rrelative The position argument specifies a location, in pixels, rela- 
tive to the current position of the cursor. 

:relative-jump The position argument specifies a loca- 

tion, in characters, relative to the current position of the 
cursor. The width of a character in pixels depends on the 
default character style for the window; the width of the 
space character is used. 

For an overview of (flavorrmethod :x-scroll-to dw: dynamic- window) and related 
facilities, see the section "Presenting Formatted Output". 

(flavorrmethod :y tvrmenu) arg Init Option 

Specifies the top edge of the menu in pixels, relative to the outside of the superior 
window. 

(flavorrmethod :y tvrsheet) top-edge Init Option 

Specifies the y-coordinate of the top edge of the window. 

y-or-n-p &optional format-string &rest args Function 

Provides a convenient and consistent interface for asking questions of the user. It 
types out a message (if supplied), reads a single character (Y or N), and returns t 
if the answer was one of the characters "y" or "Y" or "SPRCE", or nil if the answer 
was one of the characters "n" or "N" or "RUBOUT". 

y-or-n-p uses *query-io* to print the questions and read the answers. *query-io* 
is normally synonymous with *terminal-io*, but can be rebound to another stream 
for special applications. 
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If format-string is supplied and non-nil, then a fresh-line operation is performed. 
After that a message is printed as if format-string and args were given to format. 
Otherwise it is assumed that any message has already been printed by other 
means. 

Here are some examples of the use of y-or-n-p: 

(y-or-n-p "Produce listing file?" xterminal-iox) => 

Produce listing file?(Y or N) y 

T 

(y-or-n-p "Cannot connect to network host ~S. Retry?" host) => 

Cannot connect to network host TURKEY. Retry?(Y or N) n 

NIL 

y-or-n-p should only be used for questions that the user knows are coming or in 
situations where the user is known to be waiting for a response of some kind. If 
the user is unlikely to anticipate the question, or if the consequences of the an- 
swer might be irreparable, then y-or-n-p should not be used because the user 
might type ahead and thereby accidentally answer the question. For such questions 
as "Shall I delete all of your files?", it is better to use yes-or-no-p. 

(defun show-directory (&optional dirname) 
(when (not dirname) 

(if (y-or-n-p "Use your home directory? ") 
(setq dirname (user-homedi r-pathname)) 
(return-from show-directory nil))) 
(dolist (path (directory dirname)) 
(format t "~&~A~%" path))) 
=> SHOW-DIRECTORY 

(show-di rectory) 

Use your home directory? (Y or N) Y 

foo. 1 isp 

junk. text 

=> NIL 



zl:y-or-n-p &optional message (query-io zl:query-io) Function 

Provides a convenient and consistent interface for asking questions of the user. It 
types out a message (if supplied), reads a single character (Y or N), and returns t 
if the answer was one of the characters "y" or "Y" or "SPRCE", or nil if the answer 
was one of the characters "n" or "N" or "RUBOUT". 

Asks the user a question whose answer is either "yes" or "no". It types out a mes- 
sage (if supplied), reads a single character (Y or N), and returns t if the answer 
was one of the characters "y" or "Y" or "SPRCE", or nil if the answer was one of 
the characters "n" or "N" or "RUBOUT". If any other character is typed, the function 
beeps and demands a "Y or N" answer. 
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If the message argument is supplied, it is printed on a fresh line (using the rfresh- 
line stream operation). Otherwise the caller is assumed to have printed the mes- 
sage already. If you want a question mark and/or a space at the end of the mes- 
sage, you must put it there yourself; zl:y-or-n-p does not add it. query-io defaults 
to the value of zl:query-io. 

zl:y-or-n-p should only be used for questions that the user knows are coming. If 
the user is not going to be anticipating the question (for example, if the question 
is "Do you really want to delete all of your files?" out of the blue) zl:y-or-n-p 
should not be used, because the user might type ahead a T, Y, N, space, or rubout, 
and therefore accidentally answer the question. In such cases, use zl:yes-or-no-p. 

zl:y-or-n-p supplies a prompt that indicates which form of answer (single letter or 
full word plus RETURN) is required. This prompt is appended to any message that 
you supply with the function. 

(y-or-n-p "More? ") => 
More? (Y or N) Yes. 



(flavorrmethod :y-pos tvrblinker) y Init Option 

Along with the :x-pos init option, set the initial position of the blinker within the 
window. This init option is irrelevant for blinkers that follow the cursor. The ini- 
tial position for nonfollowing blinkers defaults to the current cursor position. 



(flavorrmethod :y-scroll-position dw: dynamic- window) Method 

Returns four values: 

1. The absolute location of the current viewport's top edge. 

2. The viewport's vertical extent. 

3. The window's minimum y-coordinate (typically 0). 

4. The absolute location of the viewport's bottom edge. 

For an overview of (flavorrmethod :y-scroll-position dw: dynamic- window) and re- 
lated facilities, see the section "Presenting Formatted Output". 

(flavorrmethod :y-scroll-to dw: dynamic- window) position type Method 

Scrolls the window to a specified y-coordinate. 

position The y-coordinate to scroll to. 

type The type of scrolling operation. Three possibilities exist: 

rabsolute The position argument specifies an absolute window loca- 
tion. 



Page 1438 



rrelative The position argument specifies a location, in pixels, rela- 
tive to the current position of the cursor. 

:relative-jump The position argument specifies a loca- 

tion, in lines, relative to the current position of the cur- 
sor. The height of a line in pixels depends on the default 
character style for the window. 

For an overview of (flavorrmethod :y-scroll-to dw: dynamic- window) and related 
facilities, see the section "Presenting Formatted Output". 



cp:yank-and-read-full-command numeric-arg-p numeric-arg Function 

The c-n-Y Command Processor command accelerator. It yanks back the last com- 
mand typed for editing. 

cp:yank-and-read-full-command is a function that is suitable for use as a com- 
mand-accelerator's function. However, the easiest way to make use of this facility 
is to have the command tables in your applications that use accelerator characters 
inherit from "Colon Full Command". 

For an overview of cp:yank-and-read-full-command and related facilities: See the 
section "Managing Your Program Frame". 



yes-or-no-p &optional format-string &rest args Function 

Provides a convenient and consistent interface for asking questions of the user. It 
types out a message (if supplied), reads a word (Yes or No), and returns t if the 
answer was the word "Yes", or nil if the answer was the word "No", yes-or-no-p 
allows completion, so you can type any subset of the word "Yes" or "No" followed 
by the END or RETURN keys. 

yes-or-no-p uses *query-io* to print the questions and read the answers. *query- 
io* is normally synonymous with *terminal-io*, but can be rebound to another 
stream for special applications. 

If format-string is supplied and non-nil, a fresh-line operation is performed. After 
that a message is printed as if format-string and args were given to format. Oth- 
erwise it is assumed that any message has already been printed by other means. 

Here are some examples of the use of yes-or-no-p: 

(yes-or-no-p "Shall I delete all of your files?") => 
Shall I delete all of your files?(Yes or No) noRETURN 
NIL 

(yes-or-no-p "List the entire set of commands?") => 
List the entire set of commands? (Yes or No) yeEND 
T 

To allow the user to answer a yes or no question with a single character, use 
y-or-n-p. yes-or-no-p whould be used for unanticipated or important questions, 
which is why it requires a multiple-action sequence to answer it. 
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Writes out a message supplied in format-string, just as though it were the con- 
trol-string to format, then reads a newline terminated word, which should be ei- 
ther 'yes' or 'no', in upper or lower case. 

(defvar xthe-hash-tablesx '()) 

(defun clear-the-hash-tables () 

(when (yes-or-no-p "~&Clear all hash tables? ") 
(mapc tf'clrhash xthe-hash-tablesx))) 

(push (make-hash-table) xthe-hash-tablesx) 
(push (make-hash-table) xthe-hash-tablesx) 

(cl ear-the-hash-tabl es) 

Clear all hash tables? yes 

-» (#<Hash-Table 32432> #<Hash-Table 32497>) 

See Also: CLtL 408, write, y-or-n-p 



zl:yes-or-no-p &optional message (query-io zl:query-io) Function 

Asks the user a question whose answer is either "Yes" or "No". It types out mes- 
sage (if any), beeps, and reads in a line from the keyboard. If the line is the string 
"Yes", it returns t. If the line is "No", it returns nil. (Case is ignored, as are lead- 
ing and trailing spaces and tabs.) If the input line is anything else, zl:yes-or-no-p 
beeps and demands a "yes" or "no" answer. 

If the message argument is supplied, it is printed on a fresh line (using the rfresh- 
line stream operation). Otherwise the caller is assumed to have printed the mes- 
sage already. If you want a question mark and/or a space at the end of the mes- 
sage, you must put it there yourself; zl:yes-or-no-p does not add it. query-io de- 
faults to the value of zl:query-io. 

To allow the user to answer a yes-or-no question with a single character, use zl:y- 
or-n-p. zl:yes-or-no-p should be used for unanticipated or momentous questions; 
this is why it beeps and why it requires several keystrokes to answer it. 

zl:yes-or-no-p supplies a prompt that indicates which form of answer (single letter 
or full word plus RETURN) is required. This prompt is appended to any message 
that you supply with the function. 

(yes-or-no-p "Detonate terminal? ") => 
Detonate terminal? (Yes or No) no 



alist-member (&key alist ) &key convert-spaces-to-dashes nil Presentation Type 

Type for accepting or presenting an association list item. 

: alist Data option specifying the list of items. The usual form of item is a 
dotted pair of the print string and its object: ((String-1 . object-1) 
(string-2 . object-2) . . . (string-n . object-n)). 
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Alternatively, items can be in the "general list" form. See the sec- 
tion "The Form of a Menu Item". One of the advantages of this 
form is that documentation for each item can be added that will ap- 
pear if the user asks for help (presses the HELP key) during an 
accept of this type. Documentation is specified with the 
: documentation keyword. See the examples section of 
alist-member. 

Two other keywords are permitted in an item list. The first is 
rstyle, specifying the character style of the presented item. 

The second is :selected-style. This keyword may only be used when 
alist-member is part of a dw: accepting- values function. It specifies 
the character style of the item when it is selected, that is, after it 
has been clicked on. The :selected-style defaults to the boldface 
version of the unselected style. 

:convert-spaces-to-dashes Presentation option specifying whether 

spaces in the print string should be converted to dashes; the default 
is nil. This option can be used to avoid space overloading when 
alist-member is being used with the command processor. 

Examples: 

(accept '((alist-member :alist (("Item 1" . a) ("Item 2" . b))) 

:convert-spaces-to-dashes t)) ==> 
Enter Item-1 or Item-2: Item-2 
B 

((ALIST-MEMBER :ALIST (("Item 1" . A) ("Item 2" . B))) 
:CON\/ERT-SPACES-TO-DASHES T) 

(present 'b '((alist-member :alist (("Item 1" . a) ("Item 2" . b))) 

:convert-spaces-to-dashes t)) ==> 
Item-2 
#<DISPLAYED-PRESENTATION 444272462> 
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(defun f il ter-al ist-example () 
(let ((operator-al ist 

'(("Gaussian" :value :gauss 

: documentation "low-pass filter") 
^"Laplacian, HP" :value :lpl-hp 
: documentation "high-pass filter") 
'Laplacian, ED" :value :lpl-ed 
: documentation "edge detector") 
'Roberts" : value : rbts 
: documentation "edge detector") 
^"Prewitt, Hz" :value :prw-hz 
: documentation "horizontal edge detector") 
'Prewitt, Vt" :value :prw-vt 
: documentation "vertical edge detector") 
^"Sobel, Hz" :value :sbl-hz 
: documentation "horizontal edge detector") 
^"Sobel, Vt" :value :sbl-vt 
: documentation "vertical edge detector")))) 
(accept ' ((al ist-member :alist , operator-al ist) 

:description "a 2-dimensional image filter")))) 

(fil ter-al ist-example) ==> 

Enter a 2-dimensional image filter: HELP 

You are being asked to enter a 2-dimensional image filter. 



These are the possible 2-dimensional image filters: 



Gaussian 
Laplacian, ED 
Laplacian, HP 
Prewitt, Hz 
Prewitt, Vt 
Roberts 
Sobel , Hz 
Sobel , Vt 



low-pass filter 
edge detector 
high-pass filter 
horizontal edge detector 
vertical edge detector 
edge detector 
horizontal edge detector 
vertical edge detector 
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Enter a 2-dimensional image filter: Laplacian, HP 

:LPL-HP 

((ALIST-MEMBER :ALIST 

(("Gaussian" :\/ALUE :GAUSS : DOCUMENTATION 
"low-pass filter") 
"Laplacian, HP" :VALUE :LPL-HP :D0CUMENTATI0N 

"high-pass filter") 
"Laplacian, ED" :VALUE :LPL-ED :D0CUMENTATI0N 

"edge detector") 
"Roberts" : VALUE :RBTS : DOCUMENTATION 

"edge detector") 
"Prewitt, Hz" :\/ALUE :PRW-HZ :D0CUMENTATI0N 

"horizontal edge detector") 
"Prewitt, Vt" :\/ALUE :PRW-\/T :D0CUMENTATI0N 

"vertical edge detector") 
"Sobel, Hz" :VALUE :SBL-HZ : DOCUMENTATION 

"horizontal edge detector") 
"Sobel, Vt" :\/ALUE :SBL-VT : DOCUMENTATION 
"vertical edge detector"))) 
:DESCRIPTION "a 2-dimensional image filter") 

Because the prompt generated by accept for input of alist-member items can 
sometimes be awkward, you may want to use the meta-presentation argument 
rdescription to change it. (See the section "The Presentation Type System: an 
Overview".) This was done in the (filter-al ist-example) above. 

The filter example also demonstrates the advantage of providing an alist of the 
general list form. The : documentation provided in the alist can add much useful 
information to the display. 

A type history is not available for the alist-member presentation type. 



alist-member is one of a number of types defined 
windowS;Sequence-types.lisp. See that file for the source code. 



in SYS:DYNAMIC- 



For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



and (&rest types) 



Presentation Type 



Compound type for accepting or presenting an object of two or more presentation 
types. Typically, the second and subsequent types are derived via the satisfies pre- 
sentation type. 



types 
Examples: 



Data arguments specifying the contributing presentation types. 
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(accept '((and sys: expression (satisfies symbolp)))) ==> 

Enter the representation of any Lisp 

object satisfying SYMBOLP: ramjet 

RAMJET 

((AND SYS:EXPRESSION 

(SATISFIES SYMBOLP))) 

(accept '((and ((integer)) ((satisfies oddp)) 

((satisfies plusp))))) ==> 
Enter an integer satisfying ODDP and 
PLUSP [default 9]: 21 
21 
((AND ((INTEGER)) 

((SATISFIES ODDP)) 

((SATISFIES PLUSP)))) 

The compound presentation type in the first example is equivalent to the symbol 
presentation type and is, in fact, how that type is defined. 

and can combine any number of satisfies types with an initial, non-satisfies type. 
The second example above shows an initial integer type used with two satisfies 
types to solicit input of odd, positive integers. 

Note that the compound type has access to the type history of the initial presenta- 
tion type, if one exists. However, it does not automatically use the value at the top 
of the history as the default value in an accept function. Rather, it uses the item 
most recently added to the type history that also satisfies the satisfies function(s). 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



boolean Presentation Type 

Type for accepting or presenting a yes-or-no answer, where "yes" is t and "no" is 
nil. 

Examples: 

(accept '((boolean))) ==> 
Enter Yes or No: No 
NIL 
((BOOLEAN)) 

(present t '((boolean))) ==>Yes 
#<DISPLAYED-PRESENTATION 4443001 53> 

A type history is not available for the boolean presentation type. 

boolean is one of a number of types defined in sys : dynamic-windows; standard- 
presentation-types. 1 isp. See that file for the source code. 
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See also the inverted-boolean presentation type. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



zweirbuffer &key (create-p :if-forced) Presentation Type 

Type for accepting or presenting Zmacs editor buffers. 

:create-p Presentation option specifying whether to create the buffer entered 
in response to an accept prompt if it does not already exist. 

The default is :if-forced. This gives the user the option of changing 
the input or creating the new buffer by terminating with 
CONTROL-RETURN, rather than just creating the buffer as in the case 
of : create-p t. 

Examples: 

(accept ' ((zwei : buffer))) ==> 

Enter an editor buffer 

[default ui-dict15.sar >sys>doouims Q:]: HELP ==> 

You are being asked to enter an editor buffer. 

These are the possible editor buffers: 
*Buffer-1* 
xDef initions-1* 

doc-29-55. 1 isp >sys>doopatch>doc-29 Q: 
miscui2.sar >sys>doomiscui Q: 

standard-presentation-types. 1 isp >sys>dynamic-windows Q: 
ui-dict15.sar >sys>doouims Q: 

Enter an editor buffer 

[default ui-dict15.sar >sys>doouims Q:]: *Buffer-l* 

#<NON-FILE-BUFFER "*Buffer-1*" 47700004> 

(accept ' ((zwei : buffer) : create-p t)) ==> 

Enter an editor buffer 

[default ui-dict15.sar >sys>doouims Q:]: foo.test 

#<NON-FILE-BUFFER "foo.test" 47700567> 

((ZWEI:BUFFER) :CREATE-PT) 

(present (zwei : make-buffer 'zwei :non-f ile-buffer) 

' ( (zwei : buffer) ) ) ==>*Buf f er-2x 
#<DISPLAYED-PRESENTATION 2746721 53> 

The zweirbuffer presentation type uses the special variable zwei:*buffer-history* 
to provide its type history. 
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For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



character Presentation Type 

Type for accepting or presenting single characters. When reading, this is just a 
single character without termination. 

Examples: 

(accept '((character)) ==> 
Enter a character: R 

ft\R 
((CHARACTER)) 

(accept '((character)) ==> 
Enter a character: r 

((CHARACTER)) 

(accept '((character)) ==> 
Enter a character: % 
tf\% 
((CHARACTER)) 

(accept '((character)) ==> 
Enter a character: 3 
tf\3 

(present #\, '((character))) ==>, 
#<DISPLAYED-PRESENTATION 445346702> 
((CHARACTER)) 

Use the character presentation type for normal, editable character input. To ac- 
cept characters that would be mistaken as input-editor commands, for example 
#\C-B, use dw:out-of-band-character instead. 

There is no type history for the character presentation type. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



character-f ace-or-style f&key device (against-default si: * standard-default-character- 
style*)) &key for-attribute-list Presentation Type 

Type for accepting either a fully specified character style, or just the face compo- 
nent. (The device argument, although implemented as a keyword, is required.) 
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rdevice Dataoptionspecifyingthedeviceforthecharacterstyle.Thereare 

four possibilities: si:*b&w-screen*, lgp:*lgp-printer*, lgp:*lgp2- 
printer*, and dmpl:*dmpl-printer*. This is normally gotten with 
the :display-device-type message to a stream. 

:against-default Data option specifying a character style against which 

the input character style is merged. This is used to limit possibili- 
ties since the merge result must be valid. See the section "Merging 
Character Styles". 

:for-attribute-list Presentation option specifying whether the character 

style should be presented in list form, for example, (:fix :bold 
: normal). The default is nil. Supply a value of t when presenting a 
character style for inclusion in the attribute list of file. 

Examples: 

(accept ' ((character-face-or-style 
:device (send xterminal-iox : display-device-type))) ==> 
Enter a character face or style: BOLD 
#<CHARACTER-STYLE NIL. BOLD. NIL 155157247> 
((CHARACTER-FACE-OR-STYLE : DEVICE 
#<B&W-SCREEN-DI SPLAY-DEVICE 1 54221 604>)) 

(accept ' ((character-face-or-style 

:device , si :*b&w-screenx))) ==> 

Enter a character face or style: DUTCH. ROMAN. NORMAL 

#<CHARACTER-STYLE DUTCH . ROMAN . NORMAL 154174235> 

((CHARACTER-FACE-OR-STYLE : DEVICE 

#<B&W-SCREEN-DI SPLAY-DEVICE 1 54221 604>)) 

The character-face-or-style presentation type does not support a type history. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



character-style (&key against-default) &key for-attribute-list Presentation Type 

Type for accepting or presenting character styles. 

ragainst-default Data option specifying a character style against which 

the input character style is merged. This is used to limit possibili- 
ties since the merge result must be valid. See the section "Merging 
Character Styles". 

:for-attribute-list Presentation option specifying whether the character 

style should be presented in list form, for example, (:fix :bold 
: normal). The default is nil. Supply a value of t when presenting a 
character style for inclusion in the attribute list of file. 
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When accepting a character style, the user is prompted for the family, face, and 
size, in that order. The first two entries must be terminated by a period, the last 
by RETURN or END. 

Examples: 

(accept '((character-style))) ==> 

Enter a valid character style: SWISS. BOLD. LARGE 

#<CHARACTER-STYLE SWISS . BOLD. LARGE 264231477> 

(present (si : parse-character-style '(:swiss :bold :large))) ==> 
SWISS. BOLD. LARGE 
#<DISPLAYED-PRESENTATION 425221 252> 

The character-style presentation type supports a type history. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



character-style-for-device f&key device (against-default si:* standard-default- 
character-style*) (allow-relative t) (allow-device-font nil)) &key for-attribute-list (pro- 
vide-subhelp t) Presentation Type 

Type for accepting or presenting character styles for a specified device. (The de- 
vice argument, although implemented as a keyword, is required.) 

rdevice Dataoptionspecifyingthedeviceforthecharacterstyle.Thereare 

four possibilities: si:*b&w-screen*, lgp:*lgp-printer*, lgp:*lgp2- 
printer*, and dmpl:*dmpl-printer*. This is normally gotten with 
the :display-device-type message to a stream. 

ragainst-default Data option specifying a character style against which 

the input character style is merged. This is used to limit possibili- 
ties since the merge result must be valid. See the section "Merging 
Character Styles". 

: allow-relative Data option specifying whether relative style specifica- 

tions, such as smaller or larger, are permitted. See the section 
"Merging Character Styles". 

:allow-device-font Dataoptionspecifyingwhetheradevicefontisper- 
mitted; the default is nil. 

For more information about device fonts, see the section "Mapping a 
Character Style to a Font". 

:for-attribute-list Presentation option specifying whether the character 

style should be presented in list form, for example, (:fix :bold 
: normal). The default is nil. Supply a value of t when presenting a 
character style for inclusion in the attribute list of file. 
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rprovide-subhelp Presentation option specifying whether to provide a 

HELP display; the default is t. Disable this if a higher-level call pro- 
vides help. 

Examples: 

(accept ' ((character-style-for-device 
:device ,si :*b&w-screenx))) ==> 
Enter a character style: FIX. BOLD. TINY 
#<CHARACTER-STYLE FIX. BOLD. TINY 154222436> 
((CHARACTER-STYLE-FOR-DEVICE : DEVICE 
#<B&W-SCREEN-DI SPLAY-DEVICE 1 54221 604>)) 

(accept ' ((character-style-for-device 

:device , lgp:*lgp2-printerx :al low-relative t))) ==> 

Enter a character style [default FIX. BOLD. TINY] : SWISS. BOLD. SAME 

#<CHARACTER-STYLE SWISS . BOLD. SAME 15212221> 

((CHARACTER-STYLE-FOR-DEVICE : DEVICE 

#<LGP2-DISPLAY-DEVICE 154173651> : ALLOW-RELATI VE T)) 

(accept ' ((character-style-for-device 

: device , si :*b&w-screenx :al low-device-font t))) ==> 

Enter a character style: DEVICE-FONT .BIGFNT 

#<CHARACTER-STYLE DEVICE-FONT . BIGFNT . NORMAL 14251534> 

((CHARACTER-STYLE-FOR-DEVICE : DEVICE 

#<B&W-SCREEN-DISPLAY-DEVICE 154221604> : ALLOW-DEVICE-FONT T)) 

character-style-for-device is a subtype of character-style, from which it inherits 
a type history. 

For an overview of presentation types and related facilitie,: see the section "Using 
Presentation Types". 



sysrcode-fragment Presentation Type 

Type for accepting or presenting pieces of Lisp code. This presentation type is a 
subtype of sysrform, and intended primarily for accessing code fragments in editor 
buffers. The following example, the definition of a translating mouse handler for 
editor commands, uses sysrcode-fragment as the from-presentation-type argument: 

(zwei :def ine-presen tat ion- to-edi tor-command- translator 
typeout-menu-argl ist-f rom-buffer 
(sys: code-fragment "Arglist" *standard-comtab* 
: gesture :hyper-meta-middle) 

(function-spec) 
(when (and (sys: val idate-function-spec function-spec) 
(fdefinedp function-spec)) 
1 (typeout-menu-argl ist , function-spec))) 
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For an overview of presentation types and related facilities: See the section "Using 
Presentation Types". 



cprcommand (&key command-table * command-table* command-table-p) &key wait- 
for-activation t Presentation Type 

Type for accepting or presenting a command processor command. 

:command-table Data option specifying the command table in which to 

find the command. The default, *command-table*, is bound to the 
command table currently in use. See the section "Managing Com- 
mand Tables". 

:wait-for-activation Presentation option specifying, when nil that the com- 
mand should be executed when the presentation is accepted. With 
the default, t, the user is required to enter an activation character 
to execute the command. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



fsrdirectory-pathname &key (default-version .-newest) (default-type nil) (default- 
name nil) dont-merge-default (direction :read) (format .-normal) Presentation Type 

Type for accepting or presenting a directory pathname. This is a directory as a 
file, that is, something like >a>b. directory, as opposed to >a>b. 

This presentation type can be useful if you need to distinguish unequivocally be- 
tween directory pathname presentations and file pathname presentations. For ex- 
ample, if you can arrange for the availability to your users of some fsrdirectory- 
pathname presentations, then mouse handlers performing directory-related func- 
tions can be defined that do not have to test whether a given pathname presenta- 
tion is a directory pathname, or extract directory objects from pathname presen- 
tations. 

fsrdirectory-pathname is a subtype of the pathname presentation type, from 
which it inherits a printer, parser, and type history. It also takes the same key- 
word arguments, as follows: 

r default- version Presentation option specifying the default version num- 

ber of an accepted file. The default value for this option is mewest, 
the newest file version. 

rdefault-type Presentation option specifying the default file type, for 

example, "lisp", "text", "data", and so on. The default value for this 
option is nil. 

rdefault-name Presentation option specifying the default file name. 

The default value for this option is nil. 
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:dont-merge-default Presentation option specifying whetherto prevent 

merging of a partially specified pathname entered by the user 
against the default pathname. The default value for this option is 
nil, meaning that merging occurs when appropriate; that is, parts of 
the pathname not entered by the user are supplied from the default. 

Suppression of merging against the default and providing a differ- 
ent default (against which merging may or may not be enabled) are 
different issues. To deal with the latter, use the rdefault option to 
accept. ( See the function accept. ) An example follows: 

(accept '((pathname) : default-type nil) 

: default (send (fs: default-pathname) 

: new-pathname :type nil 
: version : newest)) 

: direction 

Presentation option specifying either :read (the default) or rwrite. 
The value supplied is passed through to fsrcomplete-pathname and 
affects completion behavior. (See the function fsrcomplete- 
pathname.) 

Use the default (rread) if the user is likely to enter the pathname 
of an already existing file when prompted by accept, rwrite other- 
wise. 

rformat Presentation option specifying the output format of the pathname. 
There are four choices: 

mormal For example, S:>mb>dw-pgms>fancy-windows. 1 isp. This is 
the default format. 

rdirectory For example, >mb>dw-pgms>. The host, file name, and 
file type are not displayed. 

rdired For example, fancy-windows. 1 isp. Only the file name and 
type are displayed. 

reditor For example, fancy-windows. 1 isp >mb>dw-pgms S. The dis- 
play format is that used by Zmacs. 

For examples illustrating the use of these keywords in pathname presentations, see 
the presentation type pathname. 

fsrdirectory-pathname is one of a number of types defined in sys : dynamic- 
windows ;standard-presentation-types. 1 isp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



dwr dynamic- window Presentation Type 
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Type for accepting or presenting dynamic window objects. 

Examples: 

(accept ' ( (dw : dynami c-wi ndow) ) ) 
You are being asked to enter a dynamic window. 

These are the possible dynamic windows: 
Dynamic ... (19) 
Terminal 1 

Enter a dynamic window [default Terminal 1]: Terminal 1 
#<NVT-WINDOW Terminal 1 700372 deexposed> 
((DW:DYNAMIC-WINDOW)) 

(present (tv: make-window 'dw:dynamic-window) 

' ( (dw : dynami c-wi ndow) ) ) Dynami c Wi ndow 2 
#<DW: :DISPLAYED-PRESENTATION 650404277> 

The dw: dynamic- window presentation type supports a type history. 

dw: dynamic- window is one of a number of types defined in sys dynamic- 
windows ; standard-presentati on-types.l isp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



sys:expression &rest options Presentation Type 

Type for accepting or presenting expressions. An expression is the readable, print- 
ed representation of a Lisp object. The expression is not evaluated. 

options Presentation options controlling the generation of the printed rep- 
resentation. They are listed in the following table, along with the 
special variables providing each option with its default value. (Note 
that these options are the same as those available for the Common 
Lisp function write.) 
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Option Special Variable 

rescape *print-escape* 

rpretty *print-pretty* 

:abbreviate-quote *print-abbreviate-quote* 



rradix 

:base 

rcircle 

rlevel 

rlength 

:case 

rgensym 

: array 

rreadably 

: array-length 

: string-length 



*print-radix* 

*print-base* 

*print-circle* 

*print-level* 

*print-length* 

*print-case* 

*print-gensym* 

*print-array* 

*print-readably* 

*print-array-length* 
*print-string-length* 



:bit-vector-length 
: structure-contents 



*print-bit-vector-length* 
*print-structure-contents* 



The special variables are documented together in another section: 
See the section "Output Functions". Consult the documentation for 
the individual variables to find out what they do and what values 
they can have. These values are the same that can be supplied with 
the corresponding presentation options to sysrexpression. 

Examples: 

(accept ' ((sys: expression))) ==> 

Enter the representation of any Lisp object 

[default (ACCEPT ' ((SYS:EXPRESSION)))] : setq 

SETQ 

SYS:EXPRESSION 

(accept ' ((sys: expression))) ==> 

Enter the representation of any Lisp object 

[default (ACCEPT ' ((SYS:EXPRESSION)))] : (+ 33 900) 

(+ 33 900) 

SYS:EXPRESSION 



(present (net: find-object-named :network "DNA") 
'((sys expression))) ==>#<DNA-NETWORK DNA 1 370251 7> 
#<DISPLAYED-PRESENTATION 275045641 > 
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(accept ' ((sys: expression))) ==> 

Enter the representation of any Lisp object 

[default (ACCEPT ' ((SYS:EXPRESSION)))] : 

'#<DISPLAYED-PRESENTATION 2 75045641 > 

'#<DISPLAYED-PRESENTATION 275045641 > 

SYS: FORM 

The sysrexpression type occupies a unique position in the data type hierarchy, 
namely, the highest spot but for one, that occupied by t. This means that, with a 
few exceptions, sysrexpression is supertype to all other Symbolics Common Lisp 
types. 

For all data types not explicitly defined as presentation types (via define- 
presentation-type), sysrexpression serves as the access point to the presentation 
system. It provides these types with a parser, printer, and type history. In fact, it 
provides one or more of these functions to many defined presentation types as 
well. 

sysrexpression' s history includes all previously accepted Lisp objects. This is why, 
in the accept examples above, the default is always (ACCEPT ' ((SYS:EXPRESSION))); 
this expression is the most recently accepted one. 

When accessed by other types, sysrexpression' s type history is pruned to objects of 
the accessing type. For example, number and types descended from number do 
not maintain their own type histories. When a previously accepted value is needed 
to provide, say, a default value in an accept of an integer, the expression history 
is pruned to integer objects of which the most recently accepted is used as the de- 
fault. 

For an overview of presentation types and related facilities: See the section "Using 
Presentation Types". 



sysrflavor-name Presentation Type 

Type for accepting or presenting symbols that name flavors. 

Examples: 

(accept ' ((sys: flavor-name))) ==> 
Enter a flavor name: DW: PROGRAM-FRAME 
DW: PROGRAM-FRAME 
((SYS: FLAVOR-NAME)) 

(present 'dw:margin-mixin ' ((sys: flavor-name))) ==>DW:MARGIN-MIXIN 
#<DISPLAYED-PRESENTATION 275147735> 
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(accept ' ((sys: flavor-name))) ==> 

Enter a flavor name [default DW: PROGRAM-FRAME] 

DW:MARGIN-MIXIN 

((SYS: FLAVOR-NAME)) 



DW:MARGIN-MIXIN 



The sys:flavor-name presentation type supports a type history and completion. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



sysrfont 

Type for accepting or presenting loaded fonts. 

Examples: 

(accept ' ((sys: font))) ==> 

Enter a loaded font: HELP ==> 

You are being asked to enter a loaded font. 



Presentation Type 



There are 87 


possible 


loaded fon 


ts. Do you want 


to see t 


(Y or N) Yes 










These are th 


e possible 


loaded fonts: 




5X5 


DUTCH20B 


HL14I 


MEDFNTBI 


TR12BI 


BIGFNT 


DUTCH20BI 


HL18 


MEDFNTI 


TR12I 


BIGFNTB 


DUTCH20I 


HL18B 


MOUSE 


TR14 


BIGFNTBI 


EINY7 


HL18BI 


NARROW 


TR14B 


BIGFNTI 


EUREX12I 


HL18I 


SWISS12-CCAPS 


TR14I 


BOXFONT 


EUREX24I 


HL8 


SWISS12B-CCAPS 


TR18 


CPTFONT 


HIPP012 


HL8B 


SWISS20 


TR18B 


CPTFONTB 


HL10 


HL8BI 


SWISS20B 


TR8 


CPTFONTBI 


HL10B 


HL8I 


SWISS20BI 


TR8B 


CPTFONTC 


HL10BI 


JESS13 


SWISS20I 


TR8BI 


CPTFONTCB 


HL10I 


JESS13B 


SYMB0L12 


TR8I 


CPTFONTCC 


HL12 


JESS13I 


TINY 


TVFONT 


CPTFONTI 


HL12B 


JESS14 


TR10 


TVFONTB 


DUTCH14 


HL12BI 


JESS14B 


TR10B 


TVFONTBI 


DUTCH14B 


HL12I 


JESS14I 


TR10BI 


TVFONTI 


DUTCH14BI 


HL14 


MATH12 


TR10I 




DUTCH14I 


HL14B 


MEDFNT 


TR12 




DUTCH20 


HL14BI 


MEDFNTB 


TR12B 





Enter a loaded font: DUTCH20 
#<F0NT DUTCH20 260074563> 
SYS: FONT 
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(accept ' ((sys: font))) ==> 

Enter a loaded font [default DUTCH20] : SWISS20 

#<F0NT SWISS20 260160676> 

((SYS:F0NT)) 

(present (si: get-font si :*b&w-screenx si :*standard-character-setx 
'(:jess : roman :normal))) ==>JESS13 
#<DISPLAYED-PRESENTATION 440305757> 

The sysrfont presentation type supports a type history. 

sysrfont is one of a number of types defined in sys : dynamic-windows; standard- 
presentation-types. 1 isp. See that file for the source code. 

For an overview of presentation types and related facilities: See the section "Using 
Presentation Types". 



sysrform &key (environment sir*read-form-environment* environment-p) (expres- 
sion-reader nil) (expression-printer nil) (edit-trivial-errors-p zl:*read-form-edit- 
trivial-errors-p*) Presentation Type 

Type for accepting or presenting Lisp forms. 

renvironment Presentation option specifying the lexical environment 

of an input form. (For more on environments: See the section "Lexi- 
cal Environment Objects and Arguments".) 

:edit-trivial-errors Specifies, when t, that two kinds of errors should be 
checked for: If a symbol is read, check whether the symbol is 
bound. If a list whose first element is a symbol is read, check 
whether the symbol has a function definition. If an unbound symbol 
or undefined function is encountered, the parser offers to use a 
lookalike symbol in another package or calls zlrparse-ferror to let 
the user correct the input. The default is t. 

Possible values of the keywords rexpression-reader and rexpression-printer are 
functions for reading and writing expressions in languages other than Lisp, such 
as Pascal, Fortran, or C. These are for use by the debugger. 

(accept ' ((sys: form))) ==> 

Enter A Lisp expression to be evaluated 

[default (ACCEPT ' ((SYS:F0RM)))] : (symbolpt) 

(SYMBOLP T) 

((SYS: FORM)) 

(present '(symbolp t) ' ((sys: form))) ==>(SYMB0LP T) 
#<DISPLAYED-PRESENTATION 275141170> 
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Command : (SYMBOLP T) 

T 

Presented forms are evaluable. In the above examples, run in the command-or-form 
context, the (SYMBOLP T) form was entered to the Command : prompt by clicking 
left on the output of the preceding present function. This form was immediately 
evaluated. Contrast this behavior with that of sysrexpression presentations; pre- 
sented forms are quoted and not evaluable directly. 

The sysrform presentation type inherits its printer and type history from 
sysrexpression. 

For an overview of presentation types and related facilities: See the section "Using 
Presentation Types". 



sys:function-spec (&key defined-p) &key {partial-completers '(#/space)) 

Presentation Type 

Type for accepting or presenting valid function specs. (For information on function 
specs, see the section "Function Specs".) Note that a valid function spec is any- 
thing that can be parsed to record-source-file-name. It is not restricted to those 
objects actually defined as functions, except in the :defined-p t case. 

:defined-p Data option restricting function specs to those that are 

defined; possible values are t, nil, or :any, which last means any 
kind of definition. The default is nil. 

rpartial-completers Presentation option specifying a list of characters to be 
used as completers of function-spec tokens during input; the default 
list is (#/space). 

Examples: 

(present '+ ' ((sys: function-spec))) ==>+ 
#<DISPLAYED-PRESENTATION 275374421 > 

(accept ' ((sys: function-spec))) ==> 
Enter a valid function spec: + 
+ 
((SYS:FUNCTION-SPEC)) 

(accept ' ((sys: function-spec))) ==> 

Enter a valid function spec [default +] : (:PR0PERTY alpha bravo) 

(: PROPERTY ALPHA BRAVO) 

((SYS:FUNCTION-SPEC)) 
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(accept ' ((sys: function-spec :def ined-p t))) ==> 
Enter a defined function spec: (:PR0PERTY alpha bravo) 
(: PROPERTY ALPHA BRAVO) is not a defined function spec. 
Type RUBOUT to correct your input. [Abort] 

(defun (: property alpha bravo) () 1) ==> 
(: PROPERTY ALPHA BRAVO) 

(accept ' ((sys: function-spec :defined-p t))) ==> 

Enter a defined function spec 

[default (: PROPERTY ALPHA BRAVO)]: (: PROPERTY ALPHA BRAVO) 

(: PROPERTY ALPHA BRAVO) 

((SYS:FUNCTION-SPEC :DEFINED-P T)) 

The sys:function-spec presentation type supports a type history. For an overview 
of presentation types and related facilities, see the section "Using Presentation 
Types". 



sys:generic-function-name &key show-compatible-message Presentation Type 

Type for accepting or presenting function specs for generic functions. 

:show-compatible-message Presentation option specifying whether to 

also print, if defined, the name of the compatible message for the 
generic function. (Compatible messages are specified by an option to 
defgeneric, see the section "Defining a Compatible Message for a 
Generic Function".) 

Examples: 

(accept ' ((sys:generic-function-name))) ==> 

Enter a generic function name: HELP 

You are being asked to enter a generic function name. 

There are 11630 possible generic function names. 

Do you want to see them all? (Y or N) No. [Thanks, anyway.] 

Enter a generic function name: DW:DO-REDISPLAY 

DW:DO-REDISPLAY 

( (SYS : GENERI C-FUNCT I ON-NAME) ) 

(present 'sys:print-sel f ' ((sys:generic-function-name))) ==> 

SYS:PRINT-SELF 

#<DISPLAYED-PRESENTATION 275755254> 
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(present 'sys:print-sel f ' ((sys: generic-function-name) 

: show-compatible-message t)) ==>SYS:PRINT-SELF ( :PRINT-SELF) 

#<DISPLAYED-PRESENTATION 275755527> 

The sys:generic-function-name presentation type supports a type history and 
completion. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



netrhost Presentation Type 

Type for accepting or presenting a network host. 

Examples: 

(accept ' ((net:host))) ==> 

Enter the name of a host: Harpagornis 

#<LISPM-HOST HARPAGORNIS 53344734> 

((NET:H0ST)) 

(accept ' ((net:host))) ==> 

Enter the name of a host [default HARPAGORNIS]: laurent 

#<MSD0S-H0ST YVES-ST-LAURENT 533601 167> 

((NET:H0ST)) 

(present (si : parse-host "owl") ' ((net:host))) ==>0WL 
#<DISPLAYED-PRESENTATION 275435731 > 

(accept ' ((net:host))) ==> 

Enter the name of a host [default YVES-ST-LAURENT] : OWL 

#<LISPM-HOST OWL 13707365> 

((NET:H0ST)) 

The netrhost presentation type has its own parser and type history; it inherits its 
printer via netrobject, to which it is subtype, from sysrexpression. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 

instance (&optional (flavor '*)) Presentation Type 

Type for accepting or presenting flavor instances. 

flavor Data argument specifying what flavor this is an instance of; the de- 
fault leaves the flavor unspecified. 

Examples: 
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(present (tv: make-window 'dw: dynamic-window) 'instance) ==> 

Dynamic Window 1 

#<DW: :DISPLAYED-PRESENTATION #<DYNAMIC-WI . . . INSTANCE 420070634> 

(accept '((instance))) ==> 

Enter the Lisp representation of an instance [default Dynamic Window 1]: 

#<DYNAMIC-WINDOW Dynamic Window 1 3132740 deactivated> 

((INSTANCE)) 

The instance presentation type inherits its printer and parser functions — as well 
as a type history — from the sysrexpression presentation type. Thus, in the first 
accept function above, the prompt says to "Enter the representation of any Lisp 
object". We override this by providing our own prompt in the second call to 
accept. 

In the first accept form, the entered Dynamic Window 1 is in italics because it 
was entered via a mouse click on the presentation created by the present function. 
If we had tried to type in "dynamic window 1", accept would have returned the ob- 
ject DYNAMIC when the first space character was typed. 

instance is not a presentation type that you are likely to need for writing end-user 
interfaces to applications. A number of Common Lisp presentation types are in this 
category, for example, structure and hash-table. Like instance, all inherit their 
parser, printer, and type history from sysrexpression. And, as in the case of 
instance, when sysrexpression' s type history is accessed to provide, for example, a 
default value in an accept function, the history is "pruned" to objects only of the 
sought-after type. Thus, in the second accept function above, not any Lisp object 
is offered as a default, but an instance object. 

All flavors are subtype to the instance presentation type. Similarly, all structures 
are subtype to the structure type. The two types are thereby important for links 
they provide to the presentation-type system for flavors and structures, respective- 

ly. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



integer (&optional (range-low '*) (range-high '*)) &key (base 10) Presentation Type 
Type for accepting or presenting integers. 

range-low Data argument specifying a lower limit for integer objects. The de- 
fault is no lower limit. As in Common Lisp type specifications, * 
stands for an unspecified subsidiary item. 

range-high Data argument specifying an upper limit for integer 

objects. The default is no upper limit. As in Common Lisp type 
specifications, * stands for an unspecified subsidiary item. 
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:base Presentation option specifying the base used for integer presenta- 
tions; the default is 10. 

Examples: 

(accept '((integer 100))) ==> 

Enter an integer greater than or equal to 

and less than or equal to 100: 



((INTEGER 100)) 

(accept '((integer (0) (100)))) ==> 

Enter an integer greater than and less than 100: 1 

1 

((INTEGER (0) (100))) 

(present 10 '((integer) :base 8)) ==>12 
#<DISPLAYED-PRESENTATION 44541 1244> 

(accept '((integer 100))) 

Enter an integer greater than or equal to 

and less than or equal to 100: 12 

10 

((INTEGER) :BASE 8) 

(accept '((integer 100) :base 8)) ==> 

Enter an octal integer greater than or equal to 

and less than or equal to 144: 12 

10 

((INTEGER) :BASE 8) 

(present 50 '((integer 100))) ==>50 
#<DISPLAYED-PRESENTATION 445430232> 

(accept '((integer))) 

Enter an integer [default 8]: 50 

50 

((INTEGER 100)) 

(accept '((integer))) ==> 

Enter an integer [default 5]: 50 

50 

((INTEGER 100)) 

When specifying range limits, if the limits are provided without enclosing paren- 
theses, they are inclusive; with parentheses, exclusive. Contrast the first two 
present functions. 
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The 12 input to the second and third accept functions above was entered by click- 
ing on the output of the first present function. Note that, regardless of the base 
used for the integer presentation, the object returned remains the same. 

Note also in the second and third accepts that the data type returned is the one 
entered, an integer, not a range-restricted integer, even though the functions re- 
stricted the range of acceptable integers. Contrast this with the final 
present-accept pair: the object presented as a range-restricted integer is entered 
to a non-restricted integer accepting function; the object's data type (subtype, ac- 
tually) is retained. 

Finally, note that the integer presentation type supports a type history (inherited 
from sysrexpression), the source of the default value offered in the last accept 
function, but that range-restricted integer types do not. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



inverted-boolean Presentation Type 

Type for accepting or presenting a yes-or-no answer, where "yes" is nil and "no" is 
t. Use it when the sense of the internal action is inverted from the user sense. 

Examples: 

(accept '((inverted-boolean))) ==> 

Enter Yes or No: No 

T 

((INVERTED-BOOLEAN)) 

(present t '((inverted-boolean))) ==>No 
#<DISPLAYED-PRESENTATION 44431 2267> 

A type history is not available for the inverted-boolean presentation type. 

inverted-boolean is one of a number of types defined in sys : dynamic- 
windows ; standard-presentati on-types.l isp. See that file for the source code. 

See also the boolean presentation type. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



keyword Presentation Type 

Type for accepting or presenting keywords. 

Examples: 
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(accept '((keyword))) ==> 
Enter a keyword: orientation 
:0RIENTATI0N 
((KEYWORD)) 

(accept '((keyword))) ==> 

Enter a keyword [default ORIENTATION]: :sojac 

: | :S0JAC| 

((KEYWORD)) 

(accept ' ( (keyword) ) ) 
Enter a keyword: 1492 
: |1492| 
((KEYWORD)) 

(present :orientation '((keyword))) ==>0RIENTATI0N 
#<DISPLAYED-PRESENTATION 454276732> 

keyword inherits its printer and type history from the sysrexpression presentation 
type. 

keyword is one of a number of types defined in sys : dynamic-windows; standard- 
presentation-types. 1 isp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



net:local-host Presentation Type 

Type for accepting or presenting the local host. The local host is accepted and pre- 
sented as "Local". This is useful to use with or and netrhost to obtain output of 
host objects with the special syntax for a local host. 

Examples: 

(accept ' ((si : local -host))) ==> 
Enter a local host: Local 
#<LISPM-HOST OYSTERCATCHER 13702373> 
((SI:L0CAL-H0ST)) 

(present net :*local -host* ' ((si : local -host))) ==>Local 
#<DISPLAYED-PRESENTATION 275456200> 

(accept ' ((si : local -host))) ==> 

Enter a local host [default Local]: Local 

#<LISPM-HOST OYSTERCATCHER 13702373> 

((SI:L0CAL-H0ST)) 

The net:local-host presentation type is subtype to the netrhost type, but has its 
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own parser and printer. It inherits a type history from the latter, but prunes it to 
occurrences of "Local". 

net:local-host is one of a number of types defined in sys : dynamic- 
windows ; standard-presentati on-types.l isp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



netirlocal-network Presentation Type 

Type for accepting or presenting local network objects. (A local network is one to 
which the current machine is connected.) 

Examples: 

(accept ' ((neti : local -network))) ==> 

Enter a local network: HELP 

You are being asked to enter a local network. 

These are the possible local networks: 
CHAOS 
FBAND 
INTERNET 

Enter a local network: INTERNET 
#<INTERNET-NETWORK INTERNET 13700021> 
((NETI: LOCAL-NETWORK)) 

(present (car neti :*local -networks*) 

' ( (neti : 1 ocal -network) ) ) ==>FBAND 
#<DISPLAYED-PRESENTATION 27551 7001 > 

(accept ' ((neti : local -network))) 

Enter a local network [default INTERNET]: FBAND 

#<FBAND-NETWORK FBAND 261216753> 

((NETI: LOCAL-NETWORK)) 

The netirlocal-network presentation type supports its own type history. 

netirlocal-network is one of a number of types defined in sys dynamic- 
windows; standard-presentati on-types.l isp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



member (&rest elements) Presentation Type 

Type for accepting or presenting one of a series of objects. The printed representa- 
tions of the objects must be unique, that is, no two representations can be string- 
equal. 
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elements The series of objects. These objects are data arguments for this pre- 
sentation type. 

Examples: 

(accept '((member New York Stock Exchange))) ==> 

Enter New, York, Stock, or Exchange: York 

YORK 

((MEMBER NEW YORK STOCK EXCHANGE)) 

(accept '((member , (pathname "y :>pgm>ui-1 . 1 isp") 
, (pathname "y :>pgm>ui-2. 1 isp") 
, (pathname "y :>pgm>ui-3. 1 isp")))) ==> 

Enter Y:>pgm>ui-1 . 1 isp, Y:>pgm>ui-2. 1 isp, 

or Y:>pgm>ui-3. 1 isp: Y:>pgm>ui-2. 1 isp 

#P"Y:>pgm>ui-2. 1 isp" 

((MEMBER #P"Y:>pgm>ui-1 .lisp" #P"Y:>pgm>ui-2. 1 isp" 

#P"Y:>pgm>ui-3. 1 isp")) 

Because the prompt generated by accept for input of member objects can some- 
times be awkward, you may want to use the meta-presentation argument 
rdescription to change the prompt. (See the section "The Presentation Type Sys- 
tem: an Overview".) 

The member presentation type works differently from the member function in 
how it determines group membership. The presentation type merely checks to see 
if the printed representation of an object is the same as one of its elements. The 
function bases membership decisions on eql. 

There is no type history for the member presentation type. 

The dwrmember-sequence presentation type is similar to member, except that it 
takes a single argument instead of a series of arguments. See the presentation 
type dwrmember-sequence. 

For an overview of presentation types and related facilities, see the section "Pre- 
sentation Substrate Facilities". 



dwrmember-sequence (sequence) Presentation Type 

Type for accepting or presenting one of a series of objects. The printed representa- 
tions of the objects must be unique, that is, no two representations can be string- 
equal. 

sequence Data argument specifying a sequence containing the objects. 

Examples: 
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(accept ' ( (dw : member-sequence 

(Kierkegaard Heidegger Buber Barth)))) ==> 
Enter Kierkegaard, Heidegger, Buber, or Barth: Heidegger 
HEIDEGGER 
((DW:MEMBER-SEQUENCE (KIERKEGAARD HEIDEGGER BUBAR BARTH))) 

(setq adenosine-list '("AMP" "ADP" "ATP")) 
("AMP" "ADP" "ATP") 

(accept ' ((dw: member-sequence ,adenosine-l ist))) 

Enter AMP, ADP, or ATP: ATP 

"ATP" 

((DW: MEMBER-SEQUENCE ("AMP" "ADP" "ATP"))) 

Because the prompt generated by accept for input of dwrmember-sequence objects 
can sometimes be awkward, you may want to use the meta-presentation argument 
rdescription to change it. (See the section "The Presentation Type System: an 
Overview".) 

dwrmember-sequence is similar to the member presentation type, except that it 
takes a single argument instead of a series of arguments. See the presentation 
type member. 

The dwrmember-sequence presentation type does not support a type history. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



netirnamespace Presentation Type 

Type for accepting or presenting namespace objects. 

Examples: 

(present net:*namespacex ' ((neti : namespace))) ==>SCRC 
#<DISPLAYED-PRESENTATION 275467554> 

(accept ' ( (neti : namespace) ) ) 
Enter a namespace: SCRC 
#<NAMESPACE SCRC 13700207> 
((NETI: NAMESPACE)) 

(accept ' ( (neti : namespace) ) ) 

Enter a namespace [default SCRC]: SCRC 

#<NAMESPACE SCRC 13700207> 

((NETI: NAMESPACE)) 

Through flavor inheritance, the netirnamespace presentation type is subtype to 
the netrobject type, from which it inherits a type history. The history inherited in- 
cludes all accepted objects of the netrobject type; that is, no pruning of the histo- 
ry occurs. 
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For presentations of namespace classes, as opposed to the namespace objects 
themselves, use the net:namespace-class presentation type. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



net:namespace-class Presentation Type 

Type for accepting or presenting namespace classes, of which there are currently 
seven: 

:file-system 

:user 

rprinter 

metwork 

:host 

:site 

rnamespace 

Examples: 

(accept ' ((net: namespace-class))) ==> 

Enter a namespace class: printer 

:PRINTER 

((NET: NAMESPACE-CLASS)) 

(accept ' ((net: namespace-class))) ==> 
Enter a namespace class: Namespace 
: NAMESPACE 
((NET: NAMESPACE-CLASS)) 

(present :site ' ((net: namespace-class))) ==>Site 
#<DISPLAYED-PRESENTATION 275427546> 

The net:namespace-class presentation type is based on the dwrmember-sequence 
type. Neither supports a type history. 

For presentations of namespace objects, as opposed to namespace classes, use the 
netrnamespace presentation type. 

net:namespace-class is one of a number of types defined in sys : dynamic- 
windows ; standard-presentati on-types.l isp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



netrnetwork Presentation Type 

Type for accepting or presenting network objects. 

Examples: 
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(present (net: find-object-named 

:network "DNA") ' ((net: network))) ==>DNA 
#<DISPLAYED-PRESENTATION 27551 0033> 

(accept ' ((net:network))) ==> 
Enter a network: DNA 
#<DNA-NETWORK DNA 1 370251 7> 
((NET: NETWORK)) 

Through flavor inheritance, the netrnetwork presentation type is subtype to the 
netrobject type, from which it inherits a type history. The history inherited in- 
cludes all accepted objects of the netrobject type; that is, no pruning of the histo- 
ry occurs. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



dw:no-type Presentation Type 

Bogus presentation type for use with mouse handlers. dw:no-type is used to en- 
sure that handlers intended to be active only over blank areas of a window are not 
active over presentations. See the section ":blank-area Option to Mouse Handlers". 

For an overview of dw:no-type and related facilities, see the section "Using Pre- 
sentation Types". 



not (inverted-type) Presentation Type 

Type for modifying another presentation type. There is no parser or printer for 
this type; it can only be used as part of a compound type — specifically, only as 
part of an and presentation type. 

inverted-type Data argument specifying the presentation type to 

qualify. 

There is no type history for the not presentation type. Example: 

(accept '((and number ((not integer))))) 

For an overview of presentation types and related facilities, see the section "Pre- 
sentation Substrate Facilities". 



null Presentation Type 

Type for accepting or presenting a null object (nil). The null type is necessary be- 
cause no parser or printer can be defined for nil. 

Null objects are presented as "None". They can be accepted by pressing RETURN to 
the accept function prompt, or clicking on a previously presented "None". 

Examples: 
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(present nil '((null))) ==>None 
#<DISPLAYED-PRESENTATION 454227454> 

(present nil) ==>None 
#<DISPLAYED-PRESENTATION 454227707> 

(accept '((null))) ==> 
Enter a null value: <RETURN> 
NIL 
((NULL)) 

(accept '((null))) ==> 
Enter a null value: None 
NIL 
NULL 

The most common use of null is as part of an or compound presentation type. For 
such a combination, use the null-or-type presentation type. 

For an overview of presentation types and related facilities, see the section "Pre- 
sentation Substrate Facilities". 



null-or-type (presentation-type) Presentation Type 

Compound type for accepting or presenting either nil or an object of a specified 
presentation type, nil is accepted or presented as "None". 

presentation-type Data argument specifying a presentation type. 

Examples: 

(accept '((null-or-type number))) ==> 

Enter a null or type: 2.2 

2.2 

((NULL-OR-TYPE NUMBER)) 

(accept '((null-or-type number)) 

:prompt "Enter a number or Y'NoneY"') ==> 
Enter a number or "None" [default 2.2]: None 
NIL 
((NULL-OR-TYPE NUMBER)) 

(present nil '((null-or-type number))) ==>None 
#<DISPLAYED-PRESENTATION 44471 3264> 

If the type specified in the null-or-type presentation type supports a type history, 
this history is used. This is the source of the default value shown in the second 
call to accept above. 
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null-or-type is one of a number of types defined in sys : dynamic-windows; standard- 
presentation-types. 1 isp. See that file for the source code. 



number (&optional range-low range-high) &key (base 10) Presentation Type 

Type for accepting or presenting numbers. 

range-low Data argument specifying a lower limit for number objects. The de- 
fault is no lower limit. 

range-high Data argument specifying an upper limit for number 

objects. The default is no upper limit. 

:base Presentation option specifying the base used for integer presenta- 
tions; the default is 10. 

Examples: 

(accept 'number) 
Enter a number: 23 
23 
(NUMBER) 

(accept '(number :base 10)) ==> 

Enter a decimal number: 12 

12 

(NUMBER :BASE 10) 

(accept '((number 10) :base 2)) ==> 

Enter a binary number greater than or equal to 

and less than or equal to 1010: 111 

7 

((NUMBER 10) :BASE 2) 

(accept '((number 10) :base 2)) ==> 

Enter a binary number greater than or equal to 

and less than or equal to 1010: 2 

2 

((NUMBER 10) :BASE 2) 

When specifying range limits, if the limits are provided without enclosing paren- 
theses, they are inclusive; with parentheses, exclusive. 

Unlike the integer presentation type, number does not check input for violation of 
the :base specification. Thus, in the final accept function above, a 2 is entered 
and returned even though binary numbers are sought. 

number is supertype to all other numeric presentation types. See the section 
"Types of Numbers". It provides the family with its printer and parser functions. 
As with other Common Lisp types, number is subtype to sysrexpression, from 
which it inherits a type history. 
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For an overview of presentation types and related facilities, see the section "Pre- 
sentation Substrate Facilities". 



netrobject Presentation Type 

Type for accepting or presenting network objects. 

Examples: 

(accept ' ((net: object))) ==> 

Enter a namespace object: (Class) HELP==> 

You are being asked to enter a namespace object. 

These are the possible namespace classes: 
File-System Printer 
Host Site 
Namespace User 
Network 

Enter a namespace object: User JO 
#<USER JO 13731243> 
((NET: OBJECT)) 

(accept ' ((net:object))) ==> 

Enter a namespace object [default JO]: Host OYSTERCATCHER 

#<LISPM-HOST OYSTERCATCHER 13702373> 

((NET:OBJECT)) 

(present (net: find-object-named :network "chaos") 
' ((net:object))) ==>CHA0S 
#<DISPLAYED-PRESENTATION 275037261 > 

(accept ' ((net:object))) ==> 

Enter a namespace object [default OYSTERCATCHER]: CHAOS 

#<CHA0S-NETW0RK CHAOS 13700033> 

CHAOS: CHAOS-NETWORK 

When accepting netrobject input, the user is first prompted for the class of the 
object. The possible classes, from File-System to User, are listed in the help dis- 
play shown in the first example above. After entering the class of net object, the 
user should type a space and then the name of the object itself. 

The netrobject presentation type is built on a flavor of the same name. It inherits 
its printer and type history from the sysrexpression presentation type. It is, in 
turn, supertype to several other network-related types: 

netrhost 

netrlocal-host 

netirnamespace 
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netrnetwork 

netirsite 

netruser 

When you wish handle a particular class of network object, as opposed to any ob- 
ject, one of the above presentation types might be more suitable than netrobject. 

netrobject is one of a number of types defined in sys : dynamic-windows; standard- 
presentation-types. 1 isp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



or (&rest types) Presentation Type 

Compound type for accepting objects as one of two or more possible presentation 
types. (Presenting objects as or types is not useful.) 

types Data arguments specifying the possible presentation types. 

Examples: 

(present 'some-symbol) ==>S0ME-SYMB0L 
#<DISPLAYED-PRESENTATION 274336643> 

(present "some-string") ==>some-string 
#<DISPLAYED-PRESENTATION 274337201 > 

(accept '((or symbol string))) ==> 
Enter a symbol or a string: SOME-SYMBOL 
SOME-SYMBOL 
SYMBOL 

(accept '((or symbol string))) ==> 

Enter a symbol or a string [default SOME-SYMBOL]: some-string 

"some-string" 

STRING 

Some tips on the use of or: If you give it to accept directly or use it in a 
cprdefine-command, remember to specify a type for the default using the 
: default-type keyword, or is useful for automatically writing token rescanning 
multiple syntax parsers for your own presentation type. Use it in an rexpander. 
See the section "rexpander Option to define-presentation-type". The types null-or- 
type, token-or-type, and type-or-string are provided for the common cases. 

The or presentation type has access to the sysrexpression type history. The value 
provided as a default in an accept of an or type is the most recently accepted ob- 
ject whose presentation type is one of the possible types. 

For an overview of presentation types and related facilities, see the section "Pre- 
sentation Substrate Facilities". 
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dw:out-of-band-character (&rest chars) Presentation Type 

Type for accepting characters that would normally be interpreted as input editor 
commands, such as the shifted characters c-B or c-E. 

chars Data arguments specifying the shifted characters. 

Examples: 

(accept ' ((dw:out-of-band-character #\c-F #\m-Scroll #\m-C))) ==> 
Enter one of the characters c-F, n-SCROLL, or n-sh-C: n-SCROLL 
#\m-Scrol 1 
((DW:OUT-OF-BAND-CHARACTER #\c-F #\m-Scroll #\m-C)) 

(accept ' ((dw:out-of-band-character #\c-F #\m-SCR0LL #\m-C))) ==> 

Enter one of the characters c-F, n-SCROLL, or n-sh-C 

[default Meta-Scrol 1] : c-F 

tf\c-F 

((DW:OUT-OF-BAND-CHARACTER #\c-F #\m-Scroll #\m-C)) 

dw:out-of-band-character is subtype to the character presentation type, from 
which it inherits its printer and type history. The type history is pruned to include 
only previously accepted out-of-band characters. 

To accept or present ordinary characters, use character. See the presentation type 
character. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



package Presentation Type 

Type for accepting or presenting packages. 

Examples: 

(present (find-package 'dynamic-windows) '((package))) ==> 

DYNAMIC-WINDOWS 

#<DISPLAYED-PRESENTATION 274353464> 

(accept '((package))) ==> 

Enter a package: DYNAMIC-WINDOWS 

#<Package DYNAMIC-WINDOWS 45652740> 

((PACKAGE)) 

(accept '((package))) ==> 

Enter a package [default DYNAMIC-WINDOWS]: SCL 

#<Package SYMBOLICS-COMMON-LISP 46405507> 

((PACKAGE)) 
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The package presentation type supports a type history. 

package is one of a number of types defined in sys : dynamic-windows; standard- 
presentation-types. 1 isp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Pre- 
sentation Substrate Facilities". 



pathname &key (default-version .-newest) (default-type nil) (default-name nil) dont- 
merge-default (direction :read) (format -.normal) Presentation Type 

Type for accepting or presenting pathnames. 

: default- version Presentation option specifying the default version num- 

ber of an accepted file. The default value for this option is mewest, 
the newest file version. 

: default-type Presentation option specifying the default file type, for 

example, "lisp", "text", "data", and so on. The default value for this 
option is nil. 

:default-name Presentation option specifying the default file name. 

The default value for this option is nil. 

:dont-merge-default Presentation option specifying whetherto prevent 

merging of a partially specified pathname entered by the user 
against the default pathname. The default value for this option is 
nil, meaning that merging occurs when appropriate; that is, parts of 
the pathname not entered by the user are supplied from the default. 

Suppression of merging against the default and providing a differ- 
ent default (against which merging may or may not be enabled) are 
different issues. To deal with the latter, use the rdefault option to 
accept. ( See the function accept. ) An example follows: 

(accept '((pathname) : default-type nil) 

: default (send (fs: default-pathname) 

: new-pathname :type nil 
: version : newest)) 

: direction 

Presentation option specifying either :read (the default) or rwrite. 
The value supplied is passed through to fsrcomplete-pathname and 
affects completion behavior. (See the function fsrcomplete- 
pathname.) 

Use the default (rread) if the user is likely to enter the pathname 
of an already existing file when prompted by accept, rwrite other- 
wise. 



Page 1474 



rformat Presentation option specifying the output format of the pathname. 
There are four choices: 

rnormal For example, S:>mb>dw-pgms>fancy-windows. 1 isp. This is 
the default format. 

rdirectory For example, >mb>dw-pgms>. The host, file name, and 
file type are not displayed. 

rdired For example, fancy-windows. 1 isp. Only the file name and 
type are displayed. 

reditor For example, fancy-windows. 1 isp >mb>dw-pgms S. The dis- 
play format is that used by Zmacs. 

Examples: 

(present #p"y : >yosemi te-s>gol d . text" ) ==>Y : >yosemi te-s>gol d . text 
#<DISPLAYED-PRESENTATION 274370245> 

(present #p"y :>yosemite-s>gold. text" '((pathname) 

:format :editor)) ==> 
gold. text >yosemite-s Y: 
#<DISPLAYED-PRESENTATION 274370523> 

(accept '((pathname))) ==> 

Enter the pathname of a file: gold. text >yosemite-s Y: 

#P" Y : >yosemi te-s>gol d . text" 

((PATHNAME) : FORMAT : EDITOR) 

(accept '((pathname) : default-version 1)) ==> 

Enter the pathname of a file 

[default Y:>yosemite-s>gold. text] : silver 

#P"Y:>yosemite-s>sil ver . text. 1 " 

FS:LMFS-PATHNAME 

(accept '((pathname) :defaul t-type "data" 

:defaul t-name "the-rabbit")) ==> 
Enter the pathname of a file 

[default Y:>yosemite-s>sil ver .text. 1] : Y:>yosemite-s> 
#P" Y : >yosemi te-s>the- rabbi t . data . newest" 
FS:LMFS-PATHNAME 

(accept '((pathname) :dont-merge-defaul t t)) ==> 

Enter the pathname of a file 

[default Y:>yosemite-s>the-rabbit.data] : other-varmints 

#P" Y : other-varmi nts" 

FS:LMFS-PATHNAME 
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(accept '((pathname))) ==> 

Enter the pathname of a file 

[default Y:>other-varmints] : VIXEN :/b-bunny/y-s. data 

#P" V I XEN : /b-bunny/y-s . data" 

FS:UNIX42-PATHNAME 

The pathname presentation type supports a type history. 

pathname is one of a number of types defined in sys : dynamic-windows; standard- 
presentation-types. 1 isp. See that file for the source code. 

Two subtypes to pathname are included among the documented predefined presen- 
tation types: 

• fsrdirectory-pathname 

• fsrwildcard-pathname 

For an overview of presentation types and related facilities, see the section "Pre- 
sentation Substrate Facilities". 

sysrprinter Presentation Type 

Type for accepting or presenting printers, that is, hardcopy output devices. 

Examples: 

(accept ' ((sys:printer))) 

Enter a printer [default Symbolics Paradigm]: Symbolics Paradigm 

#<LGP2-PRINTER PARADIGM 13701250> 

SYS:PRINTER 

(present (net: find-object-named :printer "Asahi") 

' ((sys:printer))) ==>Asahi Shimbun 
#<DISPLAYED-PRESENTATION 275641 455> 

The sysrprinter presentation type supports a type history. 

sysrprinter is one of a number of types defined in sys : dynamic-windows; standard- 
presentation-types. 1 isp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 

netirprotocol-name (&key service) Presentation Type 

Type for accepting or presenting names of network protocols. 

Examples: 
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(accept ' ((neti : protocol -name))) ==> 
Enter a network protocol: Domain-Simple 
:DOMAIN-SIMPLE 
((NETI: PROTOCOL-NAME)) 

(present : converse ' ((neti : protocol -name))) ==>C0N\/ERSE 
#<DISPLAYED-PRESENTATION 275603433> 

(present (car neti :*protocol-l istx) 

' ( (neti : protocol -name) ) ) ==>MANDELBROT 
#<DISPLAYED-PRESENTATION 275607026> 

There is no type history for the neti:protocol-name presentation type. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 

dw:raw-text Presentation Type 

Type providing access to the individual characters from which all textual presenta- 
tions are constructed. This type is for the exclusive use of mouse handlers, usually 
as the from-presentation-type argument. (For more on handlers, see the section 
"Mouse Handler Facilities".) You cannot use it to accept or present text or charac- 
ters. 

The following example is the source code for a translating mouse handler defined 
on dw:raw-text, translating it to an internal presentation type, dw::character- 
style-family: 

(def i ne-presentati on-transl ator 

si : characters-character-styl e-f ami 1 y 
(dw: raw-text dw: : character-style-family) (bp) 
(when (< (second bp) (string-length (first bp))) 
(let ((char (aref (first bp) (second bp)))) 
(si :cs-family (si : char-style char))))) 

zweirbp is a presentation type inheriting from dw:raw-text, and used for accessing 
text characters in editor buffers. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



satisfies (satisfies-function) Presentation Type 

Type for forming compound presentation types using the presentation type and by 
specializing an initial type with the argument satisfies-function, a predicate that re- 
turns t or nil when applied to the object in question. The satisfies type is used 
only as part of an and presentation type. For example, 
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(accept '((and character ((satisfies digit-char-p))) 

:description "a digit")) 

For an overview of presentation types and related facilities: See the section "Using 
Presentation Types". 



sequence (&optional (type '*)) &key (sequence-delimiter #\,) (echo-space t) 

Presentation Type 

Type for accepting or presenting one or more objects of a specified presentation 
type. 

type Presentation type for the objects in the sequence. The specified type 

is a data argument to the sequence presentation type. 

The default type argument, '*, results in the use of the t presenta- 
tion type. Because t has no parser and uses princ as its printer, not 
supplying the type argument when you use the sequence presenta- 
tion type does not produce useful results. 

rsequence-delimiter Presentation option specifying the character used to 
delimit items in the sequence; the default is the comma character, 

#v 

When accepting objects in an enumerated sequence, the user must 
enter the sequence-delimiter character between items. 

:echo-space Presentation option specifying whether to echo a space 

character after the comma (or other rsequence-delimiter character) 
is typed; the default is t. 

relement-default o6/'ec£Specifies that object is to be used as the default when 
doing a recursive accept of the first element of the sequence. This 
is different than specifying the default for the sequence, since you 
might want the sequence default to be empty, and yet you might 
want to specify that if the user decides to type an element, that ele- 
ment should be parsed against a particular default. For example: 
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(accept '((sequence pathname)) :default '()) 
Enter pathnames of files: tennis 

;completes to "ACME:tennis" 
=> (#P"ACME: tennis") 

( (SEQUENCE-ENUMERATED FS : LMFS-PATHNAME) ) 

(accept '((sequence pathname) 

: element-default #P"S:>Joe>bowl ing. text") 
: default '()) 
Enter pathnames of files: golf 

;completes to "ACME:>Joe>golf.text.newest" 
=> (#P"ACME:>Joe>gol f. text. newest") 

( (SEQUENCE-ENUMERATED FS : LMFS-PATHNAME) ) 

Although not a subtype, sequence can be regarded as a specialized version of the 
sequence-enumerated presentation type. Instead of specifying a series of presenta- 
tion types as in the case of sequence-enumerated, you specify only one type for 
the entire series of objects. In fact, when objects are entered individually to an 
accept of a sequence, the types of the objects, although identical, are enumerated. 
Observe this behavior in the first example below. 

Examples: 

(accept '((sequence package))) ==> 

Enter one or more packages 

[default SYMBOLICS-COMMON-LISP]: SCL, DW, TV, SCT 

(#<Package SYMBOLICS-COMMON-LISP 46405507> 

#<Package DYNAMIC-WINDOWS 45652740> 

#<Package TV 46031453> 

#<Package SYSTEM-CONSTRUCTION-TOOL 46366410>) 

((SEQUENCE-ENUMERATED PACKAGE PACKAGE PACKAGE PACKAGE)) 

(present '(0 16 32 64) '((sequence ((integer) :base 16)))) 
#<DISPLAYED-PRESENTATION 274631 670> 

(accept '((integer))) ==> 

Enter an integer: 40 

64 

((INTEGER) :BASE 16) 

(accept '((sequence integer))) ==> 

Enter one or more integers: 0, 10, 20, 40 

(0 16 32 64) 

((SEQUENCE ((INTEGER) :BASE 16))) 

Note that when you have presented a sequence of objects, the objects are subse- 
quently acceptable as input either as individual objects or as the sequence. This is 
shown by the last three examples above. We present a series of integers, and sub- 
sequently click on one of them (40) to enter it to an accept or an integer; and 
then click on the entire sequence to give it to an accept of and integer sequence. 
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The syntax for use of presentation type arguments with sequence is shown in the 
next example. 

(accept '((sequence sys:printer) : sequence-del i miter #\;) 

The sequence presentation type has access to the type history supported, if any, 
by the specified type. 

For an overview of presentation types and related facilities: See the section "Using 
Presentation Types". 



sequence-enumerated (&rest data-types) &key (sequence-delimiter "") (echo-space t) 

Presentation Type 

Compound type for accepting or presenting a sequence of objects, each of a speci- 
fied presentation type. 

data-types 

The presentation types of the objects. These are the data arguments 
to the sequence-enumerated presentation type. 

rsequence-delimiter Presentation option specifying the character used to 

delimit items in the sequence; the default is the comma character, 

M ti 

* • 

When accepting objects in an enumerated sequence, the user must 
enter the sequence-delimiter character between items. 

:echo-space Presentation option specifying whether to echo a space 

character after the comma (or other rsequence-delimiter character) 
is typed; the default is t. 

relement-defaults '(objectl object2 ...) Specifies an enumerated se- 

quence of objects to be used one by one as the default for each re- 
cursive accept involved in accepting elements of the enumerated 
sequence. This is different than specifying the default for the se- 
quence, since you might want the sequence default to be empty, and 
yet you might want to specify that if the user decides to type an 
element, that element should be parsed against a particular default. 
For example: 

(accept '((sequence-enumerated pathname pathname) 

: el ement-def aul ts (#P" ACME : >JDoe>f i 1 e . text" 

#P" ACME : >Fred>f i 1 e . text" ) ) 
:provide-defaul t nil) 

Enter the pathnames of two files: a, b 

;completes to "ACME:>JDoe>a.text.newest, ACME:>Fred>b.text.newest" 
=> (UP" ACME : >JDoe>a . text . newest" #P" ACME : >Fred>b . text . newest" ) 
((SEQUENCE-ENUMERATED FS : LMFS-PATHNAME FS : LMFS-PATHNAME) ) 
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Examples: 

(accept '((sequence-enumerated (integer 1 10) 

sys:form string))) ==> 
Enter an integer greater than or equal to 1 and less 
than or equal to 10, A Lisp expression to be evaluated, 
and a string: 5, (setq alpha "bravo"), "Not very useful" 
(5 (SETQ ALPHA "bravo") "Not very useful") 
((SEQUENCE-ENUMERATED (INTEGER 1 10) SYS:F0RM STRING)) 

(present ' (, (pathname "y :>ui . 1 isp") telson 

, (find-package "dynamic-windows")) 
'((sequence-enumerated pathname symbol package))) ==> 
Y:>ui.lisp, TELSON, and DYNAMIC-WINDOWS 
#<DISPLAYED-PRESENTATION 444476230> 

The sequence-enumerated presentation type does not support a type history. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 

tv: sheet Presentation Type 

Type for accepting or presenting window objects. 

Examples: 

(accept ' ((tv: sheet))) ==> 

Enter a window [default Graphic Editor 1]: HELP ==> 

You are being asked to enter a window. 

These are the possible windows: 

Command ... (3) Dynamic . . . (19) 

Converse Fsmaint ... (2) 

Converse Frame 1 Graphic Editor 1 

Dex ... (6) Main ... (2) 

Enter a window [default Dex Frame 1]: Graphic Editor 1 
#<PROGRAM-FRAME Graphic Editor 1 701735 deexposed> 
((TV: SHEET)) 

(present (tv: make-window 'dw:dynamic-window) 

' ((tv: sheet))) Dynamic Window 1 
#<DW: :DISPLAYED-PRESENTATION 650364063> 

The tvrsheet presentation type supports a type history. 

tvrsheet is one of a number of types defined in sys : dynamic-windows; standard- 
presentation-types. 1 isp. See that file for the source code. 



Mode Line Window 4 


Zmail 


. .. (4) 


Terminal 1 


Zwei . 


. . (3) 


Typein ... (3) 


Who . . 


• (8) 


Zmacs ... (3) 
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For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



netirsite Presentation Type 

Type for accepting or presenting site objects. 

Examples: 

(present net :*local -site* ' ((neti :site))) ==>SCRC 
#<DISPLAYED-PRESENTATION 275626405> 

(accept ' ((neti : site))) ==> 
Enter a site: SCRC 
#<SITE SCRC 13700014> 
((NETI :SITE)) 

Through flavor inheritance, the netirsite presentation type is subtype to the 
netrobject type, from which it inherits a type history. The history inherited in- 
cludes all accepted objects of the netrobject type; that is, no pruning of the histo- 
ry occurs. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 

sysrstack-frame Presentation Type 

Type for accepting or presenting stack frames. This presentation type is intended 
primarily for use by the debugger and debugging functions. 

The following example shows entry into the debugger from an editor typeout win- 
dow. The debugger was entered because oddp was called with no arguments. The 
frame, ODDP, containing the error is at the top of the stack. 

Command: (oddp) ==> 

Trapr The function ODDP was called with too few arguments. 
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ODDP: 

-Missing args:- 

Arg (INTEGER) 
s-A, RESUME: Supply the missing arguments. 
s-B: Retry the FUNCALL-N-RETURN instruction 

s-C, RBORT : Return to Breakpoint ZMACS in Editor Typeout Window 

s-D: Editor Top Level 

s-E: Restart process ZMACS-WINDOWS 

— > Eval (program): (setq stk-frm (accept ' ((sys:stack-f rame)))) ==> 
Enter a stack frame: ODDP 

(tf<DTP-LOCATIUE 52700741> . #<TOO-FEW-ARGUMENTS-TRAP 44070612>) 
— > Eval (program): (present stk-frm ' ((sys: stack-frame))) ==>0DDP 
#<DISPLAYED-PRESENTATION 276024201 > 
-> Abort Abort 
Return to Breakpoint ZMACS in Editor Typeout Window 

sys:stack-frame does not support a type history. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



string f&optional size) &key delimiters Presentation Type 

size An integer specifying the length of the string. 

Type for accepting or presenting strings. 

rdelimiters Presentation option specifying a list of characters serv- 

ing as string delimiters (terminators) during input of strings to 
accept. The default delimiters are #\return and #\end. 

Examples: 

(accept '((string))) ==> 

Enter a string: "Morgan the Pirate" 

"Morgan the Pirate" 

((STRING)) 

(accept '((string) delimiters (#\line))) ==> 

Enter a string (end with LINE) 

[default Morgan the Pirate]: Several species 

of smal 1 , furry 

creatures gathered 

together in a cave . . . 



Page 1483 



"Several species 
of smal 1 , furry 
creatures gathered 
together in a cave ..." 
((STRING) :DELIMITERS (tfXLine)) 

(present "Another whimsical string") ==>Another whimsical string 
#<DISPLAYED-PRESENTATION 2747601 65> 

(accept ' ((string))) 

Enter a string: Another whimsical string 

"Another whimsical string" 

STRING 

The string presentation type supports a type history. 

For an overview of presentation types and related facilities: See the section "Using 
Presentation Types". 



subset (&rest keywords) Presentation Type 

Type for accepting or presenting zero or more objects from a group of keyword 
identifiers. 

keywords The set of keywords. These are data arguments to the subset pre- 
sentation type. 

Examples: 

(accept '((subset :mercenaria :mya :mytilus))) ==> 
Enter a subset of the identifiers MERCENARIA, 
MYA, and MYTILUS: Mercenaria, Mytilus 
(:MERCENARIA :MYTILUS) 
((SUBSET :MERCENARIA : MYA :MYTILUS)) 

(present '(:mya) '((subset :mercenaria :mya :mytilus))) ==>MYA 
#<DISPLAYED-PRESENTATION 444621 057> 

When accepting input of this type, the user must separate identifiers with com- 
mas. If input is terminated without any identifiers having been entered, accept re- 
turns nil. 

A type history is not available for the subset presentation type. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 
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symbol Presentation Type 

Type for accepting or presenting symbols. 

Examples: 

(accept '((symbol))) 
Enter a symbol : RNA 
RNA 
((SYMBOL)) 

(accept '((symbol))) 

Enter a symbol [default RNA]: DNA 

DNA 

((SYMBOL)) 

(present 't-RNA) 
#<DISPLAYED-PRESENTATION 274753204> 

(accept '((symbol))) 

Enter a symbol [default RNA]: T-RNA 

T-RNA 

SYMBOL 

The symbol presentation type inherits its parser, printer, and type history from 
the sysrexpression presentation type. 

To accept or present symbol names as opposed to symbol objects, use the symbol- 
name presentation type. 

For an overview of presentation types and related facilities: See the section "Using 
Presentation Types". 



symbol-name Presentation Type 

Type for accepting or presenting a symbol name, that is, the print name of a sym- 
bol. (For accepting or presenting symbol objects, use the symbol presentation 
type.) 

Examples: 

(accept ' ( (symbol -name) ) ) 
Enter a symbol name: T-M-S 
"T-M-S" 
((SYMBOL-NAME)) 

(present "T-M-S" ' ((symbol -name))) ==>T-M-S 
#<DISPLAYED-PRESENTATION 444645436> 

The symbol-name presentation type inherits its printer and type history from the 
string presentation type. 
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symbol-name is one of a number of types defined in sys : dynamic- 
windows ; standard-presentati on-types.l isp. See that file for the source code. 

For an overview of presentation types and related facilities: See the section "Using 
Presentation Types". 



sctrsystem ((&key (patchable-only nil))) Presentation Type 

Type for accepting or presenting systems. 

:patchable-only Data option restricting systems to those that are 

patchable; the default is nil. 

Examples: 

(accept ' ((set: system))) ==> 
Enter a system: Zmail 
#<SCT:SYSTEM ZMAIL 520001430> 
((SCT: SYSTEM)) 

(accept ' ((set: system : patchable-only t))) ==> 
Enter a system: Documentation Database 
#<SYSTEM DOC 261374510> 
((SCT: SYSTEM : PATCHABLE-ONLY T)) 

(present (set: find-system-named 'extended-help) 

' ((set: system))) ==>Extended Help 
#<DISPLAYED-PRESENTATION 274651 506> 

(present (car set : xal 1 -systems*) ' ((set: system))) ==>System 
#<DISPLAYED-PRESENTATION 274641 244> 

The sctrsystem presentation type supports a type history. 

sctrsystem is one of a number of types defined in sys: dynamic-windows; standard- 
presentati on-types.l isp. See that file for the source code. 

For an overview of presentation types and related facilities: See the section "Using 
Presentation Types". 



sctrsystem-version Presentation Type 

Type for accepting or presenting a system version designator. Three kinds of des- 
ignators are permitted: 

• a positive, non-zero integer 

• one of the special keywords rreleased, rlatest, or mewest 

• an arbitrary keyword 
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Examples: 

(accept ' ((set: system-version))) ==> 

Enter a version designator: 2 

2 

((SCT: SYSTEM-VERSION)) 

(accept ' ((set: system-version))) ==> 
Enter a version designator: Released 
: RELEASED 
((SCT: SYSTEM-VERSION)) 

(accept ' ((set: system-version))) ==> 
Enter a version designator: arbitrary 
: ARBITRARY 
((SCT:SYSTEM-VERSION)) 

(present : newest ' ((set: system-version))) ==>Newest 
#<DISPLAYED-PRESENTATION 274677471 > 

The sctrsystem-version presentation type does not support a type history. 

sctrsystem-version is one of a number of types defined in sys : dynamic- 
windows ; standard-presentati on-types.l isp. See that file for the source code. 

For an overview of presentation types and related facilities: See the section "Using 
Presentation Types". 



t Presentation Type 

Type that is supertype to all other presentation types. 

t occupies a necessary spot (the top) in the type hierarchy, and is important for 
that reason. However, it has no parser and cannot be used with accept. Moreover, 
objects presented as t presentations are not mouse-sensitive in any input context. 

One of the key uses for the t type is in mouse handlers, as the from-presentation- 
type or to-presentation-type. If the former, it means that the handler in question is 
potentially applicable to any type of presentation; if the latter, it means that the 
handler is potentially applicable in any input context. See the section "Mouse Han- 
dler Concepts". 

For an overview of presentation types and related facilities: See the section "Using 
Presentation Types". 

timertime-interval Presentation Type 

Type for accepting or presenting intervals of time. Internally, time intervals are in 
seconds; externally, in seconds, minutes, hours, days, weeks, and years, nil is rep- 
resented as "never". 
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Examples: 

(accept ' ((time: time-interval ))) ==> 
Enter a time interval : 1 second 
1 
((TIME:TIME-INTERUAL)) 

(accept ' ((time: time-interval ))) ==> 

Enter a time interval [default 1 second]: 1 minute 

60 

((TIME:TIME-INTERUAL)) 

(accept ' ((time: time-interval ))) ==> 

Enter a time interval [default 1 minute]: 1 hour 

3600 

((TIME:TIME-INTERUAL)) 

(present 3661 ' ((time: time-interval ))) ==>1 hour 1 minute 1 second 
#<DISPLAYED-PRESENTATION 276047342> 

(present nil ' ((time: time-interval ))) ==>never 
#<DISPLAYED-PRESENTATION 276047575> 

Note that time intervals are specified with integers only. 

The timertime-interval presentation type supports a type history. 

timertime-interval is one of a number of types defined in sys : dynamic- 
windows ; standard-presentati on-types.l isp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". See the function si:parse-interval-or-never. 

time:time-interval-60ths Presentation Type 

Type for accepting or presenting intervals of time. Internally, time intervals are in 
60ths of a second; externally, in seconds, minutes, hours, days, weeks, and years. 
nil is represented as "never". 

Examples: 

(accept ' ((time: time-interval-60ths))) ==> 
Enter a time interval 60ths: 1 second 
60 
((TIME:TIME-INTER\/AL-60THS)) 

(accept ' ((time: time-interval-60ths))) ==> 

Enter a time interval 60ths [default 1 second]: 1 minute 

3600 

((TIME:TIME-INTER\/AL-60THS)) 
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(accept ' ((time: time-interval-60ths))) ==> 

Enter a time interval 60ths [default 1 minute]: 1 hour 

216000 

((TIME:TIME-INTERUAL-60THS)) 

(present 3661 ' ((time: time-interval-60ths))) ==>1 minute 1 second 
#<DISPLAYED-PRESENTATION 276061 445> 

(present 30 ' ((time: time-interval-60ths))) ==>0 seconds 
#<DISPLAYED-PRESENTATION 276062366> 

(present 31 ' ((time: time-interval-60ths))) ==>1 second 
#<DISPLAYED-PRESENTATION 276062621 > 

(present nil ' ((time: time-interval-60ths))) ==>never 
#<DISPLAYED-PRESENTATION 276061 700> 

Note that time intervals are specified with integers only; also, that they are round- 
ed to the nearest second when presented. 

The time:time-interval-60ths presentation type supports a type history. 

time:time-interval-60ths is one of a number of types defined in sys : dynamic- 
windows ; standard-presentati on-types.l isp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



timertimezone &key force-numeric-p Presentation Type 

Type for accepting or presenting timezones. 

Timezones are represented externally either by commonly accepted abbreviations, 
for example, "EST" (for Eastern Standard Time), or by a signed digit string, for 
example, "-0500". The sign of the digit string indicates the location of the time- 
zone relative to Greenwich; positive means east, negative west. 

Internally, timezones are represented by numbers in the form n.O or n.5. Note that 
the sign of the externally displayed digit string is opposite to that of the number 
used internally. The printed digit string "-0530", for example, corresponds to an in- 
ternal representation of 5.5. 

:force-numeric-p Presentation option specifying whether a timezone is 

presented only by a signed digit string. The default is nil; this 
causes the timezone's unique abbreviation, if there is one, to be 
printed. If a unique abbreviation is not available, the digit string is 
printed regardless of the value supplied for this option. 

Examples: 
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(accept ' ((time: timezone))) ==> 

Enter a defined timezone symbol or an hour offset from GMT 

such as +0500 (east of GMT) or -0330 (west of GMT) : EST 

5 

((TIME:TIMEZONE)) 

(accept ' ((time: timezone))) ==> 

Enter a defined timezone symbol or an hour offset from GMT 

such as +0500 (east of GMT) or -0330 (west of GMT) : -0500 

5 

((TIME:TIMEZONE)) 

(present 5 ' ((time: timezone))) ==>EDT 
#<DISPLAYED-PRESENTATION 274454265> 

(present 5 ' ((time: timezone) : force-numeric-p t)) ==>-0400 
#<DISPLAYED-PRESENTATION 274454520> 

Note in the last two examples, created in July, that the displayed presentations re- 
flect daylight savings time. At sites in timezones for which straightforward rules 
exist governing the change from standard to daylight-savings time and back again, 
the timezone utility automatically switches over to the appropriate abbreviation 
and digit string. For other timezones, the switch must be made manually. In either 
case, timertimezone presentations display the current setting for daylight savings 
time. For more information, see the section "Specifying a Time Zone for Your 
Site". 

The timertimezone presentation type does not support a type history. 

timertimezone is one of a number of types defined in sys : dynamic- 
windows ; standard-presentati on-types.l isp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



token-or-type (special-tokens otherwise-type) Presentation Type 

Compound type for accepting or presenting a special token — for example "None", 
"Any", "All" — or an object of a specified type. 

special-tokens Data argument specifying a list of tokens. The list is 

an alist: each item is a dotted pair of a print string and its object: 
((String-1 . object-!) (string-2 . object-2) . . . (string-n . object-n)) 

otherwise-type Data argument specifying the presentation type to use 

for accepting or presenting objects other than listed tokens. 



Examples: 
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(defun try-it () 

(accept ' ((token-or-type (("either" . :either) 

("neither" . :neither) 
("both" . :both)) 
((subset :fixed-wing : rotary-wing)))) 
: prompt 
"Enter \"f ixed-wing\" , \"rotary-wing\" , Y'eitherV, Y'neitherV, or Y'bothY"')) 

(try-it)==> 

Enter "fixed-wing", "rotary-wing", "either", "neither", or "both": Fixed-Wing 

(:FIXED-WING) 

SUBSET 

(try-it)==> 

Enter "fixed-wing", "rotary-wing", "either", "neither", or "both": neither 
:NEITHER 

((ALIST-MEMBER :ALIST (("either" . :EITHER) ("neither" . :NEITHER) ("both" . :B0TH))) 
DESCRIPTION "special token") 

Here is an example of a common idiom in the system: 

(cp:def ine-command (com-f ilename-example : command-table "GLOBAL" 

:provi de-output-destination-keyword nil ) 
((pathnames '((token-or-type (("All" : al 1 ) ) 

((sequence pathname)))) 
: default : al 1 ) ) 
(present pathnames)) 

If the presentation type specified by otherwise-type supports a type history, the his- 
tory is available for objects of that type. 

token-or-type is one of a number of types defined in sys : dynamic- 
windows ; standard-presentati on-types.l isp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



type-or-string (presentation-type) &key reject-null-string string-if-quoted 

Presentation Type 

Compound type for accepting or presenting objects of a specified type or strings. 

presentation-type Data argument specifying the presentation type to use 

for accepting or presenting objects which are not strings. 

:reject-null-string Takes a boolean value. A non-null value allows you to 
give no default value, but still not allow a null (string) as input. A 
null value means that this presentation type refuses a null string 
only if there is a non-null default. This keyword enables you to con- 
trol whether or not a null string is allowed as input separately from 
the default value. 
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:string-if-quoted Takes a boolean value, which controls whether the fol- 

lowing is parsed as a type or as a string when explicit quotes are 
present. 

((type-or-string type) :string-if-quoted string-if-quoted) 

The default, if :string-if-quoted is not supplied, or is nil, is to al- 
ways try to parse it first as a type and then as a string if that 
fails. However, if :string-if-quoted is t, then explicit quoting (with 
doublequotes) will force the object to be parsed as a string. 



Examples: 

(accept '((type-or-string net:user))) 
Enter a user: JWALKER 
#<USER JWALKER 6434203> 
SI:USER 

(accept '((type-or-string net:user)) 

: default (dw: presentation-type-default 'net: user) 
Enter a user [default JWALKER]: JBIRD 
"JBIRD" 
STRING 

(present 'JWALKER '((type-or-string net:user))) ==>JWALKER 
#<DISPLAYED-PRESENTATION 445112577> 

(present "JWALKER" '((type-or-string net:user))) ==>JWALKER 
#<DISPLAYED-PRESENTATION 445105072> 

Here is an example of :string-if-quoted: 

;;; the following treats "3" as an integer 
(accept '(type-or-string integer)) 

;;; the following treats "3" as a string 

(accept '((type-or-string integer) :string-if-quoted t) 

Although the type specified by presentation-type might support a type history, ac- 
cepting a type-or-string does not automatically display the default; you have to 
provide one to accept yourself. This is illustrated in the second accept form 
above. 

Note in the present examples that the objects presented have the same printed 
representation. The first, however, is an netruser object, the second a string ob- 
ject. Each will only be mouse-sensitive in the appropriate input context. 

type-or-string is one of a number of types defined in sys : dynamic- 
windows ; standard-presentati on-types.l isp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 
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time:universal-time &key base-time past-p must-have timezone long-date brief (re- 
place-relative-time nil) present-based Presentation Type 

Type for accepting or presenting universal times. (Universal time is measured in 
seconds elapsed since midnight, Jan 1, 1900, GMT.) 

When accepting universal times, a large variety of input formats are possible. For 
more information and examples, see the section "Reading Dates and Times". 

The following keyword options, all presentation arguments, are available. The first 
three — :base-time, :past-p, and :must-have — affect the input of universal 
times. The remaining options, — rtimezone, :long-date, rbrief, rreplace-relative- 
time, and :present-based — affect their output. The discussion of each includes 
examples. 

:base-time Presentation option specifying a base time from which 

defaults are taken for unspecified components when accepting a uni- 
versal time. 

The base time is specified as the number of seconds since midnight, 
January 1, 1986 (that is, 1/01/00 00:00:00). In the following example, 
the base time is midnight, January 1, 1986. 

Example: 

(accept ' ((time: universal -time) :base-time 2713928400 

description "a date in 1986"))) ==> 
Enter a date in 1986: 3/2 ==>3/02/86 00:00:00 
2719112400 
((TIME:UNI\/ERSAL-TIME) :BASE-TIME 2713928400) 



:past-p Presentation option specifying whether partially specified times de- 
fault to the nearest corresponding universal time in the past or fu- 
ture; the default is nil. 

The following examples were created in 7/86. 

Examples: 

(accept ' ((time: universal -time))) ==> 

Enter a universal time: 3/2 ==>3/02/87 00:00:00 

2750648400 

((TIME:UNI\/ERSAL-TIME)) 

(accept ' ((time:universal-time))) ==> 

Enter a universal time 

[default 3/02/87 00:00:00]: 8/2 ==>8/02/86 00:00:00 

2732328000 

((TIME:UNI\/ERSAL-TIME)) 
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(accept ' ((time: universal -time) :past-p t)) ==> 

Enter a universal time in the past 

[default 8/02/86 00:00:00]: 3/2 ==>3/02/86 00:00:00 

2719112400 

((TIME:UNIUERSAL-TIME) :PAST-P T) 

(accept ' ((time:universal-time) :past-p t)) ==> 

Enter a universal time in the past 

[default 3/02/86 00:00:00]: 8/2 ==>8/02/85 00:00:00 

2700792000 

((TIME:UNI\/ERSAL-TIME) :PAST-P T) 

:must-have Presentation option specifying that the year field or 

second field or both must be explicitly entered when accepting a 
universal time. The required fields are provided as a list of key- 
words. 

Example: 

(accept ' ((time:universal-time) :must-have (:year year))) ==> 

Enter a universal time, year is required 

[default 7/07/86 19:19:00]: 12/12 ==> 

no year suppl ied 

Type RUBOUT to correct your input. 

Enter a universal time, year is required 

[default 7/07/86 19:19:00]: 12/12/47 00:00:00 

1512968400 

((TIME:UNI\/ERSAL-TIME) :MUST-HA\/E (YEAR)) 



rtimezone Presentation option specifying the timezone used when 

presenting universal times. time:*timezone* provides the default 
value. 

Supply the value as a number (either n or n.S): specifies Green- 
wich Mean Time; positive numbers timezones to the west of Green- 
wich; negative numbers timezones to the east. (For more on time- 
zone representations, see the presentation type timertimezone.) 

Examples: 

(present 123456789 ' ((time:universal-time) 

:timezone -5)) ==>12/1/03 02:33:09 
#<DISPLAYED-PRESENTATION 274337427> 

(present 123456789 ' ((time:universal-time) 

:timezone 0)) ==>11/30/03 21:33:09 
#<DISPLAYED-PRESENTATION 2743401 15> 
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(present 123456789 ' ((time: universal -time) 

:timezone 5)) ==>11/30/03 16:33:09 
#<DISPLAYED-PRESENTATION 274337662> 

(present 123456789 ' ((time:universal-time) 

:timezone 5.5)) ==>11/30/03 16:03:09 
#<DISPLAYED-PRESENTATION 2743451 25> 



:long-date Presentation option specifying that the date be present- 

ed as in the following example when presenting universal times; 

(present 123456789 ' ((time:universal-time) 

: long-date t)) ==> 
Monday the thirtieth of November, 1903; 4:33:09 pm 
#<DISPLAYED-PRESENTATION 274353534> 



rbrief Presentation option specifying whether presented times should be 
printed briefly, that is, without the seconds field. Contrast the fol- 
lowing two examples: 

(present (time: get-universal -time) 

'((time: universal -time))) ==>7/07/86 14:55:35 
#<DISPLAYED-PRESENTATION 274421 523> 

(present (time: get-universal -time) 

' ((time:universal-time) :brief t)) ==>7/7/86 14:55 
#<DISPLAYED-PRESENTATION 274421 756> 



:replace-relative-time Presentation option specifying that if a relative time, 
for example, 3 minutes from now, is supplied, it should be replaced 
with the actual time in the output history. The default is nil, since 
usually if you are giving a relative time and re-run that command, 
you want the same relative offset from the current time, not the 
time the command was previously run. 

:present-based Presentation option specifying that missing components 

in the supplied time default to the beginning of the smallest unsup- 
plied unit of time. For example, 5:00 pm means 5:00 pm today, 
whether it is before or after 5:00 pm. Thursday means Thursday of 
this week, whether it is currently Monday or Friday. The default is 
nil, meaning that missing components default to the future. 

For example, if it is Wednesday, December 27, and you specify Monday: 
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(accept ' (time: universal -time)) 

Enter a universal time [default 12/28/89 10:00:00]: Monday 

=> 1/01/90 00:00:00 

2840158800 

(TIME:UNIUERSAL-TIME) 

(accept ' ((time:universal-time) : present-based t)) 

Enter a universal time [default 1/01/90 00:00:00]: Monday 

=> 12/25/89 00:00:00 

2839554000 

((TIME:UNI\/ERSAL-TIME) : PRESENT-BASED T) 

time:universal-time is one of a number of types defined in SYS:DYNAMic- 
windows;PRESENTATION-types.lisp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



netruser Presentation Type 

Type for accepting or presenting user objects. 

Examples: 

(present si:*userx ' ((si : user))) ==>REG 
#<DISPLAYED-PRESENTATION 275633757> 

(accept ' ((si : user))) ==> 
Enter a user: REG 
#<USER REG 13730364> 
((SI:USER)) 

Through flavor inheritance, the netruser presentation type is subtype to the 
netrobject type, from which it inherits a type history. The history inherited in- 
cludes all accepted objects of the netrobject type; that is, no pruning of the histo- 
ry occurs. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



fsrwildcard-pathname &key (default-version .-newest) (default-type nil) (default-name 
nil) dont-merge-default (direction :read) (format -.normal) Presentation Type 

Type for accepting or presenting pathnames that include wildcard characters. 

This presentation type can be useful if you need to distinguish unequivocally be- 
tween pathname presentations that include wildcard characters (asterisks) and oth- 
er file pathname presentations. For example, if you can arrange for the availability 
to your users of some fsrwildcard-pathname presentations, then mouse handlers 
performing functions specifically on pathnames containing wildcards can be defined 
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that do not have to test whether a given pathname presentation includes a wild- 
card character. 

fsrwildcard-pathname is a subtype of the pathname presentation type, from 
which it inherits a printer, parser, and type history. It also takes the same key- 
word arguments, as follows: 

: default- version Presentation option specifying the default version num- 

ber of an accepted file. The default value for this option is mewest, 
the newest file version. 

:default-type Presentation option specifying the default file type, for 

example, "lisp", "text", "data", and so on. The default value for this 
option is nil. 

:default-name Presentation option specifying the default file name. 

The default value for this option is nil. 

:dont-merge-default Presentation option specifying whetherto prevent 

merging of a partially specified pathname entered by the user 
against the default pathname. The default value for this option is 
nil, meaning that merging occurs when appropriate; that is, parts of 
the pathname not entered by the user are supplied from the default. 

Suppression of merging against the default and providing a differ- 
ent default (against which merging may or may not be enabled) are 
different issues. To deal with the latter, use the rdefault option to 
accept. ( See the function accept. ) An example follows: 

(accept '((pathname) : default-type nil) 

: default (send (fs: default-pathname) 

: new-pathname :type nil 
: version : newest)) 

: direction 

Presentation option specifying either :read (the default) or rwrite. 
The value supplied is passed through to fsrcomplete-pathname and 
affects completion behavior. (See the function fsrcomplete- 
pathname.) 

Use the default (rread) if the user is likely to enter the pathname 
of an already existing file when prompted by accept, rwrite other- 
wise. 

rformat Presentation option specifying the output format of the pathname. 
There are four choices: 

mormal For example, S:>mb>dw-pgms>fancy-windows. 1 isp. This is 
the default format. 

rdirectory For example, >mb>dw-pgms>. The host, file name, and 
file type are not displayed. 
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rdired For example, fancy-windows. 1 isp. Only the file name and 
type are displayed. 

reditor For example, fancy-windows. 1 isp >mb>dw-pgms S. The dis- 
play format is that used by Zmacs. 

For examples illustrating the use of these keywords in pathname presentations, see 
the presentation type pathname. 

fsrwildcard-pathname is one of a number of types defined in sys : dynamic- 
windows ;standard-presentation-types. 1 isp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 



tvrwindow Presentation Type 

Type for accepting or presenting old-style (static) window objects. 

Examples: 

(present (tv: make-window 'tv: window) ' ((tv: window))) ==> 
Window 2 
#<DW: :DISPLAYED-PRESENTATION #<WIND0W Win... ( (TV : WINDOW) ) 420205722> 

(accept ' ((tv: window))) 
Enter an old-style window: Window 2 
#<WIND0W Window 2 3133400 deactivated> 
((TV:WIND0W)) 

The tvrwindow presentation type supports a type history. 

tvrwindow is one of a number of types defined in sys : dynamic-windows; standard- 
presentation-types. 1 isp. See that file for the source code. 

For an overview of presentation types and related facilities, see the section "Using 
Presentation Types". 

sysr%draw-line xl yl x2 y2 alu draw-end-point sheet-or-raster Function 

This is analogous to the rdraw-line message to tvrgraphics-mixin. 

sysr%draw-rectangle width height x y alu sheet-or-raster Function 

This is analogous to the r draw-rectangle message to tvrstream-mixin. 

sysr%draw-triangle xl yl x2 y2 x3 y3 alu sheet-or-raster Function 

This is analogous to the r draw- triangle message to tvrgraphics-mixin. 
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graphics:2pi Variable 

An approximation to 2ji in double floating-point format. 

For an overview of graphics:2pi and related functions: See the section "Other Ba- 
sic Facilities for Graphic Output". 

:alu Option 

Specifies the drawing mode for a drawing function. Possible values for this 
option are: 

:draw Pixels specified by the drawing function are turned on, regardless 
of whether some of the pixels were already on. This is the default 
drawing mode. 

rerase Pixels specified by the drawing function are turned off, regardless 
of whether some of the pixels were already off. 

:flip Pixels specified by the drawing function are turned on if they were 

previously off, and off if they were previously on. 

Additionally, numeric and color-extended alu operations are valid values for 
this option. Whether "on" means white or black depends on the whether or 
not the display window is in inverse video mode: if inverse video is not in ef- 
fect, on means white. 



graphics:angle-between-angles-p theta theta-1 theta-2 Function 

Returns a Boolean value: t if theta is between theta-1 and theta-2 considered clock- 
wise; otherwise nil. 

Example: 

(graphics :angle-between-angles-p (/ graphics:2pi 4) (/ graphics:2pi 8) 0) 



graphicsrbasic-pattern Flavor 

The basis for the graphics pattern drawing protocol. It has one required method: 
graphics:pattern-call-with-drawing-parameters. 



graphics:binary-decode-graphics-from-array-into-function array &rest args 

Function 

array An array with elements of type (unsigned-byte 8) produced by the 
function graphics:binary-encode-graphics-to-array, which contains 
the encoded version of a graphics function. 
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args The optional keyword rcompile. When t, the function returned is 

compiled. 

Returns a function of one argument, stream. When called, this function produces 
the same graphics output that the originally encoded function produces. See the 
section "Other Advanced Facilities for Graphic Output". 



graphics:binary-encode-graphics-to-array function Function 

function A graphics function of one argument, stream. 

Returns an array containing an encoded version of function. See the section "Other 
Advanced Facilities for Graphic Output". 



graphicsrbuild-graphics-transform &key (.-rotation 0) (.scale I) (:scale-x I) (:scale-y 
I) .-translation .-transform Function 

Creates a coordinate transformation matrix based on the values of the keyword ar- 
guments given. The transformation is a result of composing coordinate system 
transforms for scaling, rotation, and then translation, in that order. The graphics 
dictionary contains separate entries for this function's keyword arguments: 

rrotation 

: scale 

:scale-x 

:scale-y 

rtranslation 

rtransform 

For more information on coordinate transformation matrices: See the section "Ad- 
vanced Transformation Facilities". 



graphics:build-multiple-point-transform points Function 

Takes two, four, or six points (4, 8, or 12 numbers) and returns a transform ma- 
trix that converts the figure described by the first half of the points into the fig- 
ure described by the second half. 

Example: 

(graphics: build-multiple-point-transform '(0 4 10 10 10 20)) ==> 
(5/2 5/2 10 10) 



graphicsrbuilding-graphics-transform f&optional stream) &body body Function 

Returns a coordinate transformation matrix to affect the stream stream based on 
the results of the graphics transformation functions — as, for example, 
graphicsrgraphics-translate, graphicsrgraphics-rotate, or graphicsrgraphics- 
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scale — included in body, in the order in which they are specified. Use this to 
compose several operations in a specific order, rather than graphicsrbuild- 
graphics-transform, as the latter uses a canonical order, not the order of the ar- 
glist. 

Example: 

(graphics: building-graphics- transform () 

(graphics: graphics-translate 10) 

(graphics:graphics-scale 5 2) 

(graphics:graphics-rotate (/ graphics:2pi 4))) ==> 

(02-500 10) 

(graphics: build-graphics-transform : rotation (/ graphics:2pi 4) 

scale-x 5 :scale-y 2 
translation (0 10)) ==> 

(graphics:build-graphics-transform : rotation (/ graphics:2pi 4) 

scale-x 5 :scale-y 2 
translation (0 10)) ==> 

(05-200 10) 



graphics:close-path &key (alu :draw) (pattern nil) (stipple nil) (tile nil) (color nil) 
(gray-level 1) (opaque t) (mask nil) (mask-x 0) (mask-y 0) (thickness 0) (scale- 
thickness t) (line-end-shape :butt) (line-joint-shape rmiter) (dashed nil) (dash-pattern 
#(10 10) ) (initial-dash-phase 0) (draw-partial-dashes t) (scale-dashes nil) (stream 
*standard-output*) (return-presentation nil) (rotation 0) (scale 1) (scale-x 1) (scale-y 
1) (translation nil) (transform nil) Function 

Draws a straight-line segment from the current position of the graphics cursor to 
the beginning of the current path segment and ends that segment. The beginning 
of the current path segment is specified by the last graphicsrset-current-position 
operation. 

This function is intended primarily for path building, that is, within path-drawing 
functions supplied to graphics:draw-path or graphics:with-clipping-path. For ex- 
ample uses: See the function graphics:draw-path. 

The listed keyword options are common to all drawing functions and documented 
separately: See the section "Keyword Options to Drawing Functions". 

For an overview of graphics:close-path and related functions: See the section 
"Path-Drawing Functions". 



graphicsrcompose-transforms transform additional-transform 
transform 



Function 



A list of the essential six elements of a two-dimensional homoge- 
neous graphics transformation matrix describing a combination of 
scaling, rotation, and translation. 
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additional-transform A second such list. 

Destructively modifies transform so that it contains the essential elements of a new 
graphics transformation matrix that is the result of the matrix dot product of the 
matrix for additional-transform and the matrix for transform. 

The transformation effected by the result of graphicsrcompose-transforms is 
equivalent to the result obtained by first effecting the transformation represented 
by transform and then transforming the result by applying additional-transform. 
See the section "Advanced Transformation Facilities". 

Compare the following three examples: 

(defun nested () 
(graphics :with-room-for-graphics (t 100) 
(graphics :draw-l ine 100) 
(graphics:draw-l ine 100 0) 
(graphics:with-graphics-scale (t 2) 
(graphics:with-graphics-translation (t 10 20) 
(graphics:draw-rectangle 10 20 0))))) 

(defun composed () 
(graphics :with-room-for-graphics (t 100) 
(graphics:draw-l ine 100) 
(graphics:draw-l ine 100 0) 
(graphics :with-graphics-transform (t 
(graph i cs : compose- transforms 

(graphics:build-graphics-transform :scale 2) 
(graphics:build-graphics-transform :translation '(10 20)))) 
(graphics:draw-rectangle 10 20 0)))) 

(defun composed-backward () 
(graphics:with-room-for-graphics (t 100) 
(graphics:draw-l ine 100) 
(graphics:draw-l ine 100 0) 
(graphics :with-graphics-transform (t 
(graph i cs : compose- transforms 

(graphics:build-graphics-transform :translation '(10 20)) 
(graphics:build-graphics-transform :scale 2))) 
(graphics:draw-rectangle 10 20 0)))) 



graphics:compute-cubic-spline px py z &optional ex cy (cl rrelaxedj (c2 

graphics: :clj pl-prime-x pl-prime-y pn-prime-x pn-prime-y Function 

px A list of the x coordinates of the points through which the cubic 

spline is to pass. 

py A list of the y coordinates of the points through which the cubic 

spline is to pass. 
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z The number of intermediate points to be calculated. 

ex An array to be filled in with the computed x coordinates. Its length 

should be (+ N (* z (- N 1))), where N is the number of points spec- 
ified in px and py. 

cy An array to be filled in with the computed y coordinates. Its length 

should be (+ N (* z (- N 1))), where N is the number of points. 

cl The initial end condition, one of rrelaxed, rclamped, :cylic, or 

ranticyclic. The default is rrelaxed. 

c2 The final end condition, one of rrelaxed or rclamped. The default 

for the final end condition to be the same as the initial end condi- 
tion, that is, graphicsrrcl. 

pl-prime-x The x value of the initial slope if the initial end condi- 

tion is rclamped. 

pl-prime-y The y value of the initial slope if the initial end condi- 

tion is rclamped. 

pn-prime-x The x value of the final slope if the final end condition 

is rclamped. 

pn-prime-y The y value of the final slope if the final end condition 

is rclamped. 

Where a list of points is specified by the lists, px and py, graphicsrcompute-cubic- 
spline computes z additional points between each pair of specified points. The z 
points lie on a cubic spline that passes through the specified points and conform to 
the end conditions specified by cl, c2, and the remaining optional arguments. The 
function returns three values, ex, cy, and N. ex and cy are lists containing the co- 
ordinates of the original points together with the computed points inserted, and N 
is the number of points originally specified. The caller can plot lines between suc- 
cessive points of ex and cy to draw a smooth curve through the given points. For 
an explanation of the end conditions: See the function graphicsrdraw-cubic-spline. 



graphicsrcompute-cubic-spline-points (points &key (start-relaxation rrelaxed) (end- 
relaxation graphicsrrstart-relaxation) start-slope-dx start-slope-dy end-slope-dx end- 
slope-dy (number-of-samples 20|) Function 

Like graphicsrcompute-cubic-spline, except that instead of two lists of x and y co- 
ordinates of points through which to draw the spline, graphicsrcompute-cubic- 
spline-points takes a single list of alternating x and y values for the points. In- 
stead of returning two arrays, it returns a single list in a format like that of the 
input. The remaining positional arguments of graphicsrcompute-cubic-spline are 
provided by keyword arguments for graphicsrcompute-cubic-spline-points. 



graphicsreurrent-position &key (stream *standard-output*) Function 
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Returns the current position of the graphics cursor in the user coordinate system. 
Note that the value of current position may change without the cursor moving if 
the stream transform changes. 

rstream Specifies the output stream; the default is *standard-output*. 

This facility is useful with drawing functions that explictly use the graphics cur- 
sor. Such functions include graphics:draw-bezier-curve-to, graphicsrdraw- 
circular-arc-to, graphics:draw-line-to, and other facilities commonly used for cre- 
ating path-drawing functions. For examples of path-drawing functions: See the 
function graphics:draw-path. 

For an overview of graphicsrcurrent-position and related functions: See the sec- 
tion "Drawing Functions". 



:dash-pattern Option 

Specifies a sequence, usually a vector, controlling the dash pattern of a draw- 
ing function. If no pattern is specified, the default dashes are 10 pixels long 
and separated by spaces of 10 pixels. The vector must contain an even num- 
ber of elements or you will get an error. 

The following example draws a line as a series of dashes, alternating in 
length between 16 and 8 pixels, with intervening spaces of 4 pixels. Note that 
these lengths result from applying a scaling factor of 4, implemented by the 
rscale and rscale-dashes keywords. 

(graphics :with-room-for-graphics (t 200) 
(graphics :draw-l ine 25 25 100 25 

: dashed t : scale 4 
scale-thickness nil 
scale-dashes t 
dash-pattern #(4 1 2 1))) 



This option is not operable if the rdashed option is nil. 



rdashed Option 

Boolean option specifying whether lines are drawn as a series of dashes by a 
drawing function; the default is nil. 

This option is not operable if the function draws a filled (: filled t) figure. 
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(graphics :with-room-for-graphics (t 100) 
(graphics: draw-rectangle 100 100 :filled nil :dashed t)) 



graphicsrdecompose-transform transform Function 

transform 

A list of the essential six elements of a two-dimensional homoge- 
neous graphics transformation matrix describing a combination of 
scaling, rotation, and translation. 

Returns six values that describe the three basic coordinate-system transformations 
specified by transform. Transform is regarded as having been composed of a trans- 
lation, followed by a rotation, followed by a scaling. This composition has the ef- 
fect on the coordinates of any given point of first scaling those coordinates, then 
rotating them, and finally translating them. For an explanation: See the section 
"The Transformation Matrix". 

The values returned are: 

• The angle of the rotation in radians 

• The scaling factor for the x dimension 

• The scaling factor for the y dimension 

• The x offset for translation 

• The y offset for translation 

• The x skew 

(setq translate-trnsfm '(1 1 50 50)) 

;x offset = y offset = 50 
(setq rotate-trnsfm '(0 1 -1 0)) 

; rotate pi/4 radians 
(setq scale-trnsfm '(400400)) 

; scale x = scale y = 4 
(setq scale-then-rotate 

(graphics :compose-transforms scale-trnsfm rotate-trnsfm)) 
(setq composite-trnsfm 

(graph i cs : compose- transforms seal e- then- rotate transl ate-trnsf m) ) ) 
(graphics : decompose- transform composite-trnsfm) 



Page 1505 



tv:*default-arrow-length* Variable 

Bound to the default value of the ratio of the length of the arrowhead to the 
thickness of the arrow shaft of arrows drawn by graphics:draw-arrow. Initially set 
to 10. 



tv:*default-arrow-width* Variable 

Bound to the default value of the ratio of the base width of the arrowhead to the 
thickness of the arrow shaft of arrows drawn by graphics:draw-arrow. Initially set 
to 5. 



graphicsrdefstipple name (height width) f&key :pretty-name :gray-level :tv-gray) pat- 
terns Function 

Defines a stipple array named name, patterns is a list of integers, typically using 
#b, in which case there are height integers, each of which is width binary digits 
long. The keywords :gray-level and :tv-gray specify when t that the resulting stip- 
ple be added to the lists graphics::*gray-level-arrays* or tv:*gray-arrays*, re- 
spectively. 

The system defined stipples have a named array leader using the following def- 
struct: 

(defstruct (stipple-array : named-array-leader 



print-function print-stipple-array) 
constructor make-stipple-array) 

constructor-make-array-keywords (dimensions '(1 32)) 

(type 'sys:art-1b))) 



(name nil) 

(gray-level nil) 

(x-phase nil) 

) 
From this definition, the following constructor functions are derived: 
graphics:make-stipple-array, graphics:stipple-array, graphics:stipple-array- 
gray-level, graphics:stipple-array-name, graphics:stipple-array-repeat-size, and 
graphics:stipple-array-x-phase. 

Example: 

(graphics:defstipple stipples:33%-gray (3 3) (:tv-gray t) (:gray-level t)) 



graphicsrdevice-pattern Flavor 

The flavor for device-dependent patterns. It has one method, graphicsrpattern- 
call-with-drawing-parameters, which can be called with rpattern self to invoke a 
device-specific drawing protocol. 
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:draw-l-bit-raster width height raster from-x frora-y to-x to-y &optional (ones-alu 
:draw) (zeros-alu .-erase) Generic Function 

Draws a pattern onto the screen. The pattern is replicated as needed, as with 
bitblt. Unlike bitblt, which copies bits regardless of any difference in bit depth 
(element type) between the source array and the screen array, :draw-l-bit-raster 
draws one screen pixel for each source pixel (the source must be a 1-bit array). 
Bits that are on in the source are drawn using ones-alu and bits that are off are 
drawn using zeros-alu. For a 1-bit screen, the result is like bitblt would have done 
with tv:alu-seta. 

To say it another way, :draw-l-bit-raster copies pixels from a 1-bit-per-pixel source 
to the destination, which can be any pixel depth. If the destination is also 1-bit- 
per-pixel, :draw-l-bit-raster is identical to bitblt, but if the destination has more 
bits, :draw-l-bit-raster will do the "right" thing where bitblt would produce use- 
less results. For detailed information on all the arguments of :draw-l-bit-raster: 

See the function bitblt. 

For a color screen, ones-alu and zeros-alu can be color alus. So, for instance, ones 
bits might be put out in green and zeros bits in red. Even when drawing in black 
in white to a color screen, :draw-l-bit-raster should be used for drawing stipples, 
because a whole pixel needs to be drawn black for the on pixels, not just one bit 
(which is only part of a pixel). Using :draw-l-bit-raster rather than bitblt is im- 
portant in programs that run without modification on color screens. 



graphics:draw-arrow from-x from-y to-x to-y &rest args &key (arrow-head-length 
tv:*default-arrow-length*) (arrow-base-width tv:*default-arrow-width*) (alu 

:draw) (pattern nil) (stipple nil) (tile nil) (color nil) (gray-level 1) (opaque t) (mask 
nil) (mask-x 0) (mask-y 0) (thickness 0) (scale-thickness t) (line-end-shape :butt) 
(line-joint-shape rmiter) (dashed nil) (dash-pattern '(10 10) ) (initial-dash-phase 0) 
(draw-partial-dashes t) (scale-dashes nil) (stream *standard-output*) (return- 
presentation nil) (rotation 0) (scale 1) (scale-x 1) (scale-y 1) (translation nil) (trans- 
form nil) Function 

Draws an arrow. 

from-x The x-coordinate for the base of the arrow. 

from-y The y-coordinate for the base of the arrow. 

to-x The x-coordinate for the tip of the arrow. 

to-y The y-coordinate for the tip of the arrow. 

Of the listed keyword options, : arrow-head-length and :arrow-base-width are 
unique to graphics:draw-arrow and documented below. The remaining options are 
common to other drawing functions and documented separately: See the section 
"Keyword Options to Drawing Functions". 

: arrow-head-length Specifies the ratio of the length of the arrowhead to 

the thickness of the arrow shaft. The default is the value of 
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tv:*default-arrow-length*, initially set to 10; thus, if thickness is 1 
pixel, arrowhead length is 10 pixels, if thickness is 2, the length is 
20, and so on. 

(graphics :with-room-for-graphics (t 100) 
(graphics: graphics-translate 20 0) 
(graphics: draw-arrow 50 : arrow-head-length 10) 
(graphics:graphics-translate 20 0) 
(graphics:draw-arrow 50 : arrow-head-length 20) 
(graphics:graphics-translate 20 0) 
(graphics:draw-arrow 50 :thickness 2 : arrow-head-length 10)) 



t 



:arrow-base-width Specifiestheratioofthebasewidthofthearrowhead 

to the thickness of the arrow shaft. The default is the value of 
tv:*default-arrow-width*, initially set to 5; thus, if thickness is 1 
pixel, arrowhead width is 5 pixels, if thickness is 2, the width is 10, 
and so on. 

(graphics:with-room-for-graphics (t 100) 
(graphics:graphics-translate 20 0) 
(graphics:draw-arrow 50 : arrow-base-width 5) 
(graphics:graphics-translate 20 0) 
(graphics:draw-arrow 50 : arrow-base-width 10) 
(graphics:graphics-translate 20 0) 
(graphics:draw-arrow 50 :thickness 2 : arrow-base-width 5)) 




For an overview of graphics:draw-arrow and related functions: See the section 
"Drawing Functions". Example: 

(graphics:with-room-for-graphics (t 100) 

(graphics:draw-arrow 100 100 :thickness 4)) 



graphics:draw-bezier-curve start-x start-y end-x end-y control-1-x control-1-y control- 
2-x control-2-y &key (alu :draw) (pattern nil) (stipple nil) (tile nil) (color nil) (gray- 
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level 1) (opaque t) (mask nil) (mask-x 0) (mask-y 0) (thickness 0) (scale-thickness t) 
(line-end-shape :butt) (line-joint-shape rmiter) (dashed nil) (dash-pattern '(10 10) ) 
(initial-dash-phase 0) (draw-partial-dashes t) (scale-dashes nil) (stream *standard- 
output*) (return-presentation nil) (rotation 0) (scale 1) (scale-x 1) (scale-y 1) (transla- 
tion nil) (transform nil) Function 

Draws a Bezier parameterization of a cubic curve. 

The curve passes through (start-x, start-y) and (end-x, end-y). The vector from 
(start-x, start-y) to (control-1-x, control-1-y) determines the starting slope of the 
curve; its length determines the next derivative. A similar relation exists between 
(end-x, end-y) and (control-2-x, control-2-y). The curve is bounded by the quadrilat- 
eral determined by the four points. 

The following example approximates a couple of sine wave curves and shows the 
bounding quadrilaterals for each: 

(graphics :with-room-for-graphics (t 400) 

(graphics:with-graphics-translation (t 200) 

(graphics idraw-bezier-curve 200 100 200 100 -200) 
(graphics: draw-lines '(0 100 200 200 100 -200 0))) 

(graphics:with-graphics-translation (t 200 200) 

(graphics:draw-bezier-curve 200 100 200 100 -200) 
(graphics:draw-lines '(0 100 200 200 100 -200 0)))) 




The listed keyword options are common to other drawing functions and document- 
ed separately: See the section "Keyword Options to Drawing Functions". 
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For an overview of graphics:draw-bezier-curve and related functions: See the sec- 
tion "Drawing Functions". 



graphics:draw-bezier-curve-to px4 py4 px2 py2 px3 py3 &key (alu :draw) (pattern 
nil) (stipple nil) (tile nil) (color nil) (gray-level 1) (opaque t) (mask nil) (mask-x 0) 
(mask-y 0) (thickness 0) (scale-thickness t) (line-end-shape :butt) (line-joint-shape 
rmiter) (dashed nil) (dash-pattern #(10 10) ) (initial-dash-phase 0) (draw-partial- 
dashes t) (scale-dashes nil) (stream *standard-output*) (return-presentation nil) (ro- 
tation 0) (scale 1) (scale-x 1) (scale-y 1) (translation nil) (transform nil) Function 

Draws a Bezier parameterization of a cubic parabola from the current position of 
the graphics cursor to a specified end point (px4, py4). The vector from the cur- 
rent cursor position to (px2, py2) determines the starting slope of the curve; its 
length determines the next derivative. A similar relation exists between (px4, py4) 
and (px3, py3). The curve is bounded by the quadrilateral determined by the four 
points. When done, the graphics cursor is moved to the end point. 

This function is intended primarily for path building, that is, within path-drawing 
functions supplied to graphics:draw-path or graphics:with-clipping-path. For an 
example: See the function graphics:draw-path. Also: See the function 
graphics:draw-bezier-curve. 

The listed keyword options are common to all drawing functions and documented 
separately: See the section "Keyword Options to Drawing Functions". 

For an overview of graphics:draw-bezier-curve-to and related functions: See the 
section "Drawing Functions". 

(graphics :with-room-for-graphics (t 100) 
(graphics: drawing-path () 
(graphics: set-current-position 0) 
(graphics :draw-bezier-curve-to 50 50 25 75 40 0) 
(graphics:draw-l ine-to 50 0) 
(graph i cs : cl ose-path) ) ) 



M 



(flavorrmethod :draw-char tvrsheet) char x-bitpos y-bitpos &optional (alu tvrchar- 
aluf) Method 

Displays char with its upper left corner at coordinates (x-bitpos, y-bitpos). 



graphicsrdraw-circle center-x center-y radius &key (sinner-radius 0) (.start-angle 0) 
(:end-angle graphics:2pi) (:alu rdraw) (-filled t) .-color Ogray-level I) :tile .stipple .-re- 
turn-presentation .-pattern (-opaque t) -.mask (:mask-x 0) (:mask-y 0) .-thickness (scale- 
thickness t) (:line-end-shape :butt) (:line-joint-shape rmiter) .-dashed :dash-pattern 
(:initial-dash-phase 0) (:draw-partial-dashes t) .scale-dashes (stream *standard- 
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output*) (.-rotation 0) .-clockwise :join-to-path (.scale I) (:scale-x I) (:scale-y I) .-trans- 
lation .-transform Function 

Draws a circle. The circle may end up looking like an ellipse on the screen if the 
current transformation matrix does not scale x and y uniformly. 

center-x The x-coordinate for the center of the circle. 
center-y The y-coordinate for the center of the circle. 
radius The radius of the circle. 

Of the listed keyword options, rinner-radius, :start-angle, :end-angle, and 
rclockwise are unique to graphicsrdraw-circle and documented below. The remain- 
ing options are common to other drawing functions and documented separately: 
See the section "Keyword Options to Drawing Functions". 

rinner-radius Specifiestheinnerradiusofacircularringfigure;the 

default is 0. 

(graphics :with-room-for-graphics (t 100) 
(graphics :draw-ci rcle 50 50 50 : inner-radius 25)) 




rstart-angle Specifiestheangleinradiansatwhichdrawingofthe 

circle begins; the default is 0. This argument is interpreted the 
same way that the argument returned by the atan function is in- 
terpreted. Since in a window increasing y is down the screen, this 
means that angles with positive sines also point down the screen. 
(This is not the way the :draw-circular-arc message interprets an- 
gles.) To avoid confusion, use a local coordinate system oriented in 
the direction you prefer, such as with graphics:with-room-for- 
graphics. 

Used in conjunction with the :end-angle option, arbitrary circular 
arcs or wedges can be drawn. The following example draws a filled 
semicircle starting at 90 degrees and ending at 270 degrees: 

(graphics :with-room-for-graphics (t 200) 
(graphics:draw-circle 100 100 50 

: start-angle (x pi 1/2) 
: end-angle (x pi 3/2))) 
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:end-angle Specifiestheangleinradiansatwhichdrawingofthe 

circle ends; the default is graphics:2pi. Refer to the :start-angle 
option for a note about the orientation of angles and for an exam- 
ple. 

Used in conjunction with the :start-angle option, arbitrary circular 
arcs or wedges can be drawn. For an example, see the :start-angle 
option. 

rclockwise Booleanoptionspecifyingwhetherthecircleisdrawn 

in a clockwise or counterclockwise direction. The default is nil, 
counterclockwise. 

When graphicsrdraw-circle is being used as a standalone drawing 
function, this option only has a visible effect when less than a full 
circle is drawn, that is, when the :start-angle or :end-angle option 
is specified to some non-default value. The following example illus- 
trates this: 

(defun clockwise-circle (t-or-nil) 

(graphics :with-room-for-graphics (t 200) 
(graphics:draw-circle 100 100 50 

: end-angle (* .5 pi) 
:clockwise t-or-nil))) 
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(clockwise-circle t) 
(clockwise-circle nil) 




When graphicsrdraw-circle is being used as a path-drawing func- 
tion inside graphics:draw-path, this option affects path winding 
rules. For more information: See the function graphics:draw-path. 
Note that if you wish to include an arc as part of a drawing-path 
outline, you should use the graphicsrdraw-ellipse function and, in 
particular, that function's :join-to-path option, instead of 
graphicsrdraw-circle. 

For an overview of graphicsrdraw-circle and related functions: See the section 
"Drawing Functions". For information on how circles are drawn and how to obtain 
the appearance you prefer: See the section "Scan Conversion". 

See the macro graphicsrwith-coordinate-mode. 

(graphics :with-room-for-graphics (t 200) 
(graphics :draw-ci rcle 50 50 50) 

(graphics :draw-ci rcle 50 : translation '(250 50) :scale-x 2) 
(graphics :draw-ci rcle 50 :translation '(450 50) :scale-x 1.5 :rotation 1)) 






(flavorrmethod rdraw-circle tvrgraphics-mixin) center-x center-y radius &optional 
alu Method 
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Draw the outline of a circle specified by its center and radius. 



graphicsrdraw-circle-driver center-x center-y radius slice-function Function 

Scan-converts the given circle, that is, computes the coordinates of the pixels that 
lie in the circle on a two-dimensional raster grid, and calls slice-function to draw 
these pixels. See the section "Graphics Drivers". 

center-x The x-coordinate for the center of the circle. 

center-y The y-coordinate for the center of the circle. 

radius The radius of the circle. 

slice-function A function specifying how a rectangular slice of the 

circle is to be drawn on a raster device and possibly specifying any 
other operations to be performed in conjunction with drawing the 
slice. This function must take four arguments: width, the width of 
the slice; height, its height; and x and y, the coordinates of the 
slice's location. A typical slice function is 

#' (lambda (width height x y) 
(send xstandard-outputx : draw-rectangle 
width height x y :draw)) 



(flavorrmethod :draw-circular-arc tv:graphics-mixin) center-x center-y radius 
start-theta end-theta &optional (alu tvrchar-aluf) Method 

Draws a circular arc for the circle centered at center-x, center-y with radius radius. 
It draws the part of the circle swept counterclockwise from the starting angle to 
the finishing angle. The angles are assumed to be in radians and are reduced mod 
2pi before drawing. For example, drawing from pi/4 to -pi/4 draws a "C". The same 
"C" appears when you draw from pi/4 to 7pi/4. Note: the interpretation of start- 
theta and end-theta are different for this message than it is for the graphicsrdraw- 
circle start-angle and end-angle: the angles are measured as they appear, not as a 
call to zhatan would return if you gave it the position of the relevant points, since 
the positive y-direction is down. 

For tv:alu-xor, the behavior with respect to points that would fall on the same 
pixel is not defined. 



graphics:draw-circular-arc-through-point-to to-x to-y through-x through-y &key 
(alu :draw) (pattern nil) (stipple nil) (tile nil) (color nil) (gray-level 1) (opaque t) 
(mask nil) (mask-x 0) (mask-y 0) (thickness 0) (scale-thickness t) (line-end-shape 
:butt) (line-joint-shape rmiter) (dashed nil) (dash-pattern #(10 10) ) (initial-dash- 
phase 0) (draw-partial-dashes t) (scale-dashes nil) (stream *standard-output*) (re- 
turn-presentation nil) (rotation 0) (scale 1) (scale-x 1) (scale-y 1) (translation nil) 
(transform nil) Function 
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Draws a circular arc through three points. The first point is the current position. 
The final position, specified by (to-x to-y), is the second point. The third point, 
specified by (through-x through-y), also lies on the circle. 

(graphics :with-room-for-graphics (t 200) 
(graphics: drawing-path (t :filled nil) 

(graphics:with-graphics-translation (t 100 50) 
(graphics: set-current-position 0) 

(graphics:draw-ci rcular-arc-through-point-to 100 100 20 80) 
(graphics:draw-l ine-to 20 80) 
(graph i cs : cl ose-path) ) ) ) 




This function is intended primarily for path building, that is, within path-drawing 
functions supplied to graphics:draw-path or graphics:with-clipping-path. For ex- 
amples of path-drawing functions: See the function graphics:draw-path. 

The listed keyword options are common to all drawing functions and documented 
separately: See the section "Keyword Options to Drawing Functions". 

For an overview of graphics:draw-circular-arc-through-point-to and related func- 
tions: See the section "Drawing Functions". 



graphics:draw-circular-arc-to to-x to-y tangent-intersection-x tangent-intersection-y 
radius &key (alu :draw) (pattern nil) (stipple nil) (tile nil) (color nil) (gray-level 1) 
(opaque t) (mask nil) (mask-x 0) (mask-y 0) (thickness 0) (scale-thickness t) (line- 
end-shape :butt) (line-joint-shape rmiter) (dashed nil) (dash-pattern #(10 10) ) (ini- 
tial-dash-phase 0) (draw-partial-dashes t) (scale-dashes nil) (stream *standard- 
output*) (return-presentation nil) (rotation 0) (scale 1) (scale-x 1) (scale-y 1) (transla- 
tion nil) (transform nil) Function 

Draws a circular arc, with a specified radius, tangent to two lines. The first tan- 
gent passes through the current position of the graphics cursor and the point spec- 
ified by (tangent-intersection-x tangent-intersection-y). The second passes through the 
intersection point and (to-x to-y). The two tangents, articulating at (tangent- 
intersection-x tangent-intersection-y), form the "sharpened" version of the arc you 
wish to draw. 

The arc is drawn in the direction of (to-x to-y), between the two tangent intersec- 
tion points, that is, the points where the arc intersects the tangent lines. If the 
starting position of the graphics cursor is different than the first tangent intersec- 
tion point, then a straight line segment is drawn from the current cursor position 
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to the starting point of the arc. When done, the graphics cursor is moved to the 
end of the arc. The function returns four values: tangent-point-xl, tangent-point-yl, 
tangent-point-x2, and tangent-point-y2, the coordinates of the points of tangency. 

The following example draws arcs providing two rounded corners, one convex and 
one concave: 

(graphics :with-room-for-graphics (t 300) 
(graphics: drawing-path () 

(graphics:with-graphics-translation (t 100 50) 
(graphics: set-current-position 0) 
(graphics :draw-ci rcular-arc-to 200 200 200 50) 
(graphics:draw-l ine-to 200 200) 
(graphics: close-path) 
(graphics:set-current-position 0) 
(graphics:draw-l ine-to 150 0) 

(graphics:draw-ci rcular-arc-to 200 50 150 50 50) 
(graphics:draw-l ine-to 200 200) 
(graph i cs : cl ose-path) ) ) ) 




This function is intended primarily for path building, that is, within path-drawing 
functions supplied to graphics:draw-path or graphics:with-clipping-path. For ex- 
amples of path-drawing functions: See the function graphics:draw-path. 

The listed keyword options are common to all drawing functions and documented 
separately: See the section "Keyword Options to Drawing Functions". 

For an overview of graphics:draw-circular-arc-to and related functions: See the 
section "Drawing Functions". 



graphics:draw-circular-arc-to-compute-points from-x from-y 
intersection-x tangent-intersection-y radius 

from-x The x coordinate of the first tangent line. 



to-x 



to-y tangent- 
Function 
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from-y The y coordinate of the first tangent line. 

to-x The x coordinate of the second tangent line. 

to-y The y coordinate of the second tangent line. 

tangent-intersection-x The x coordinate of the intersection of the tangent 
lines. 

tangent-intersection-y The y coordinate of the intersection of the tangent 
lines. 

radius The radius of the circle to be drawn. 

Where a circular arc is to be drawn tangent to two given lines with a specified 
radius, graphics:draw-circular-arc-to-compute-points computes and returns nine 
values: 

center-x The x coordinate of center of the circle. 

center-y The y coordinate of center of the circle. 

theta-1 The starting angle of circular arc to be drawn. 

theta-2 The ending angle of circular arc to be drawn. 

clockwise A Boolean specifying, when t, that the arc is to be drawn in a 
clockwise direction from theta-1 to theta-2 or, when nil, conterclock- 
wise. 

tangent-point-xl The x coordinate of the beginning of the arc. 

tangent-point-yl The y coordinate of the beginning of the arc. 

tangent-point-x2 The x coordinate of the end of the arc. 

tangent-point-y2 The y coordinate of the end of the arc. 

theta-1, theta-2, and clockwise are calculated such that the arc drawn is never 
greater than a semicircle (> (- theta-2 theta-1) pi) and the direction is the one 
specified. 

graphics:draw-circular-ring-driver center-x center-y inner-radius outer-radius slice- 
function Function 

Scan-converts the circular ring, that is, computes the coordinates of the pixels that 
lie between an outer circle specified by major-radius and an inner circle specified 
by minor-radius on a two-dimensional raster grid, and calls slice-function to draw 
these pixels. See the section "Graphics Drivers". 

center-x The x-coordinate for the center of the circular ring. 
center-y The y-coordinate for the center of the circular ring. 
major-radius The outer radius of the circular ring. 

minor-radius The inner radius of the circular ring. 
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slice-function A function specifying how a rectangular slice of the 

circular ring is to be drawn on a raster device and possibly specify- 
ing any other operations to be performed in conjunction with draw- 
ing the slice. This function must take four arguments: width, the 
width of the slice; height, its height; and x and y, the coordinates of 
the slice's location. A typical slice function is 

#' (lambda (width height x y) 

(send xstandard-outputx : draw-rectangle width height x y :draw)) 



(flavorrmethod : draw-closed-curve tv:graphics-mixin) x-array y-array &optional 
end (alu tv:char-alufj Method 

: draw-closed-curve draws a sequence of connected line segments, using the points 
in x-array and y-array as the x and y coordinates for the end-points of the lines. It 
ensures that each particular point is drawn only once, which is necessary for pro- 
ducing a connected line with tv:alu-xor. It plots the points in the arrays until end 
elements or until it encounters nil in either of the arrays. The default for end is 
the length of x-array. alu specifies how the pixels being drawn combine with those 
already there. It plots the points in the arrays until end elements or until it en- 
counters nil in either of the arrays. 

: draw-closed-curve is the same as :draw-curve except that it closes the figure by 
joining the first and last points. 



graphics:draw-conic-section from-x from-y to-x to-y tangent-x tangent-y &key .shape 
(:alu rdrawj .-pattern .stipple stile xolor (-gray-level I) (-.opaque t) -.mask (:mask-x 0) 
(:mask-y 0) .-thickness (.scale-thickness t) (:line-end-shape ibutt) (:line-joint-shape 
rmiter) .-dashed (: dash-pattern #<ART-Q-2 550031730>J (:initial-dash-phase 0) 
(:draw-partial-dashes t) .scale-dashes (stream *standard-output*J .-return- 
presentation (-rotation 0) (scale 1) (scale-x I) (scale-y I) .-translation .-transform 

Function 

Draws a conic section through two points, <from-x from-y> and <to-x, to-y>. The 
section is tangent to the two lines whose intersection is <tangent-x, tangent-y>. The 
first tangent passes through <from-x from-y> and the point <tangent-x, tangent-y>. 
The second tangent passes through <tangent-x, tangent-y> and <to-x, to-y>. The two 
tangents, articulating at <tangent-x, tangent-y>, form the "sharpened" version of the 
section you wish to draw. Parametrically, the curve drawn is the Bezier quadratic 
curve r2*P2+2s*£(l-0*Pc+(l-0"2*Pl, where t is the parameter, PI and P2 are the 
two endpoints, Pc is the intersection of the tangents, and s is related to the shape 
parameter. 

shape The eccentricity of the conic section from a parabola: if shape=l, 
the curve is a parabola; if shape<l, the curve is an ellipse; if 
shape>l, the curve is a hyperbola. The default of shape specifies the 
curve of the least eccentricity that will satisfy the constraints. If 
you take the default, the section will always be an elliptical arc. If 
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the tangents meet at a right angle, the axes of the ellipse will be 
parallel to the tangents, and, additionally, if the magnitudes of the 
tangent lines are equal, the section will be a circular arc. If you 
specify shape to be less than or equal to 1, your bounding triangle 
can be any shape; however, keep in mind that if you specify 
shape>l, the angle at <tangent-x, tangent-y> has to be large enough 
so that its secant is at least equal to shape. 

The section is drawn in the direction of (to-x to-y). When done, the graphics cursor 
is moved to the end of the section. 

(defun conic-example (from-x from-y 

to-x to-y tan-x tan-y &optional (shape nil)) 
(graphics:with-room-for-graphics (t 200) 
(graphics:with-graphics-translation (t 50 50) 
(graphics :draw-l ine tan-x tan-y to-x to-y) 
(graphics :draw-l ine tan-x tan-y from-x from-y) 
(graphics:draw-conic-section from-x from-y 

to-x to-y tan-x tan-y : shape shape)))) 
(conic-example 100 100 0) 




(conic-example 100 100 1) 




(conic-example 100 100 40 40) 
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(conic-example 100 100 40 40 1) 




(conic-example 100 100 40 40 1.1) 




graphics:draw-conic-section-to to-x to-y tangent-x tangent-y &key shape (alu :draw) 
(pattern nil) (stipple nil) (tile nil) (color nil) (gray-level 1) (opaque t) (mask nil) 
(mask-x 0) (mask-y 0) (thickness 0) (scale-thickness t) (line-end-shape :butt) (Zme- 
joint-shape rmiter) (dashed nil) (dash-pattern #(10 10) ) (initial-dash-phase 0) (draw- 
partial-dashes t) (scale-dashes nil) (stream *standard-output*) (return-presentation 
nil) (rotation 0) (scale 1) (scale-x 1) (scale-y 1) (translation nil) (transform nil) 

Function 

Draws a conic section through two points, the current graphics cursor position and 
<to-x, to-y>. The section is tangent to the two lines whose intersection is 
<tangent-x, tangent-y>. The first tangent passes through the current position of the 
graphics cursor and the point <tangent-x, tangent-y>. The second tangent passes 
through <tangent-x, tangent-y> and <to-x, to-y>. The two tangents, articulating at 
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<tangent-x, tangent-y>, form the "sharpened" version of the section you wish to 
draw. Parametrically, the curve drawn is the Bezier quadratic curve 
r2*P2+2s*£(l-0*Pc+(l-0 A 2*Pl, where t is the parameter, PI and P2 are the two 
endpoints, Pc is the intersection of the tangents, and s is related to the shape pa- 
rameter. 

shape The eccentricity of the conic section from a parabola: if shape=l, 
the curve is a parabola; if shape<l, the curve is an ellipse; if 
shape>l, the curve is a hyperbola. The default of shape specifies the 
curve of the least eccentricity that will satisfy the constraints. If 
you take the default, the section will always be an elliptical arc. If 
the tangents meet at a right angle, the axes of the ellipse will be 
parallel to the tangents, and, additionally, if the magnitudes of the 
tangent lines are equal, the section will be a circular arc. If you 
specify shape to be less than or equal to 1, your bounding triangle 
can be any shape; however, keep in mind that if you specify 
shape>l, the angle at <tangent-x, tangent-y> has to be large enough 
so that its secant is at least equal to shape. 

The section is drawn in the direction of (to-x to-y). When done, the graphics cursor 
is moved to the end of the section. 

This function is intended primarily for path building, that is, within path-drawing 
functions supplied to graphics:draw-path or graphics:with-clipping-path. For ex- 
amples of path-drawing functions: See the function graphics:draw-path. 

With the exception of rshape, documented above, the listed keyword options are 
common to all drawing functions and documented separately: See the section "Key- 
word Options to Drawing Functions". 

For an overview of graphics:draw-conic-section-to and related functions: See the 
section "Path-Drawing Functions". 



graphics:draw-cubic-spline points &key {start-relaxation rrelaxed) {end-relaxation 
graphics::start-relaxation) start-slope-dx start-slope-dy end-slope-dx end-slope-dy 
{number-of-samples 20) &allow-other-keys {alu :draw) (pattern nil) {stipple nil) {tile 
nil) {color nil) (gray-level 1) (opaque t) (mask nil) (mask-x 0) (mask-y 0) (thickness 
0) (scale-thickness t) (line-end-shape :butt) (line-joint-shape rmiter) (dashed nil) 
(dash-pattern '(10 10) ) (initial-dash-phase 0) (draw-partial-dashes t) (scale-dashes 
nil) (stream *standard-output*) (return-presentation nil) (rotation 0) (scale 1) 
(scale-x 1) (scale-y 1) (translation nil) (transform nil) Function 

Draws a cubic spline through a series of points. 

points A list of points in the form (xl yl x2 y2 ... xn yn). 

Of the listed keyword options, : start-relaxation, :end-relaxation, :start-slope-dx, 
:start-slope-dy, :end-slope-dx, :end-slope-dy, and :number-of-samples are unique 
to graphics:draw-cubic-spline and documented below. The :number-of-samples 
documentation includes an example. The remaining options are common to other 
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drawing functions and documented separately: See the section "Keyword Options to 
Drawing Functions". 

: start-relaxation Determinestheboundarycondition(derivative)ofthe 

curve at its starting point (xl, yl). Four values are possible: 

rrelaxed The derivative is set to a value that continues the trend 
of the curve established by neighboring points. This is the 
default. 

rcyclic If you specify this value, then the value of :end- 
relaxation must also be rcyclic. This forces the deriva- 
tives at the two end-points of the curve to be equal. When 
the starting and ending points are equal, this results in a 
smooth, continuous curve. This — that is, the specifica- 
tion of identical start and end points — is the normal way 
to make use of the cyclic option. If the starting and end- 
ing points specified by the user are not equal, the drawing 
function adds the beginning point on to the end of the list 
of points it uses, resulting in a closed curve in which a 
straight line connects the starting and ending point. 

ranti-cyclic If you specify this value, then the value of rend- 
relaxation must also be ranti-cyclic. This forces the 
derivatives at the two end-points of the curve to be equal 
in magnitude but opposite in sign. When the starting and 
ending points are equal, this causes the curve to come to 
a point. This — that is, the specification of identical start 
and end points — is the normal way to make use of the 
anti-cyclic option. If the starting and ending points speci- 
fied by the user are not equal, the drawing function adds 
the beginning point on to the end of the list of points it 
uses, resulting in a closed curve in which a straight line 
connects the starting and ending point. 

rclamped Clamps the derivative to the values specified by the 
:start-slope-dx, :start-slope-dy, :end-slope-dx, and rend- 
slope-dy options. 

(defun spline-relaxation (start-relaxation) 
(graphics:with-room-for-graphics (t 50) 

(graphics:draw-cubic-spline '(0 20 20 40 40 20 20 20) 

:number-of-samples 5 
: start-rel axati on start-rel axati on) ) ) 

(spline-relaxation :cyclic) 
(spline-relaxation :anti-cycl ic) 
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:end-relaxation Determinestheboundaryconditior<derivative)off;he 

curve at its ending point {xn, yn). It defaults to the value of rstart- 
relaxation. Four values are possible: 

rrelaxed The derivative is set to a value that continues the trend 
of the curve established by neighboring points. 

rcyclic If you specify this value, then the value of rstart- 
relaxation must also be rcyclic. This forces the deriva- 
tives at the two end-points of the curve to be equal. When 
the starting and ending points are equal, this results in a 
smooth, continuous curve. This — that is, the specifica- 
tion of identical start and end points — is the normal way 
to make use of the cyclic option. 

ranti-cyclic If you specify this value, then the value of rstart- 
relaxation must also be ranti-cyclic. This forces the 
derivatives at the two end-points of the curve to be equal 
in magnitude but opposite in sign. When the starting and 
ending points are equal, this causes the curve to come to 
a point. This — that is, the specification of identical start 
and end points — is the normal way to make use of the 
anti-cyclic option. 

rclamped Clamps the derivative to the values specified by rstart- 
slope-dx, rstart-slope-dy, rend-slope-dx, and rend-slope-dy 

options. 

rstart-slope-dx Specifies the dx component of the derivative at the 

starting point (xl, yl) of the curve. If you wish to specify this value, 
then you must supply : start-relaxation : clamped and specify the 
remaining three slope values. 

rstart-slope-dy Specifies the dy component of the derivative at the 

starting point {xl, yl) of the curve. If you wish to specify this value, 
then you must supply : start-relaxation : clamped and specify the 
remaining three slope values. 

rend-slope-dx Specifies the dx component of the derivative at the 

ending point {xn, yn) of the curve. If you wish to specify this value, 
then you must supply : end-relaxation : clamped and specify the re- 
maining three slope values. 

rend-slope-dy Specifies the dy component of the derivative at the 

ending point {xn, yn) of the curve. If you wish to specify this value, 
then you must supply : end-relaxation : clamped and specify the re- 
maining three slope values. 

mumber-of-samples Thaiumberofntermediatepointsgeneratedbetween 

each pair of points specified in the points argument. The default is 
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20. 

Because the curve is drawn through each intermediate point, the 
more such points the smoother the curve, but the longer it takes to 
get drawn. This is illustrated by the following example: 



(defun cubic-spline-example (n) 
(graphics :with-room-for-graphics (t 450) 
(graphics:with-graphics-translation (t 200 200) 
(let ((points-1 (list 50 25 90 40 70 30 50 70 

70 80 70 50 100 90 100 40 110 
130 30 150 40 130 20 145 160 20 
145 35 170 40 190 40 190 200 30 
220 20 240 40 250 20 260 270 20)) 
(points-2 (list 160 -200 60 -80 -40 -70 100 40 190 

145 130 144 129 200 200 300 200 330 60 
230 -80 160 -200))) 
(graphics:draw-cubic-spl ine points-1 :number-of-samples 3 

:thickness 4) 
(graphics:draw-cubic-spl ine points-2 

: start-relaxation :anti -cyclic 



number-of-samples n 
thickness 4))))) 



(cubic-spline-example 1) 
(cubic-spline-example 5) 



A reasonable :number-of-samples for the inner spline was deter- 
mined, by trial and error, to be 3. For the outer spline, 4 or 5 
seems about right, but try a range of values and note the trade-off 
between smoothness and speed. (For best results, REFRESH the 
screen each time you run this example.) 

For an overview of graphics:draw-cubic-spline and related functions: See the sec- 
tion "Drawing Functions". 

(graphics:with-room-for-graphics (t 50) 

(graphics:draw-cubic-spl ine '(0 20 20 30 0) : number-of-samples 5)) 



(flavorrmethod :draw-cubic-spline tv:graphics-mixin) px py z &optional curve- 
width alu cl c2 pl-prime-x pl-prime-y pn-prime-x pn-prime-y Method 

Draws a cubic spline curve that passes through a sequence of points. The arrays 
px and py hold the x and y coordinates of the sequence of points; the number of 
points is determined from the active length of px. Through each successive pair of 
points, a parametric cubic curve is drawn with the :draw-curve message, using z 
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points for each such curve. If curve-width is provided, the : draw- wide-curve mes- 
sage is used instead, with the given width. The cubics are computed so that they 
match in position and first derivative at each of the points. At the end points, 
there are no derivatives to be matched, so the caller must specify the boundary 
conditions, cl is the boundary condition for the starting point, and it defaults to 
rrelaxed; c2 is the boundary condition for the ending point, and it defaults to the 
value of cl. The possible values of boundary conditions are: 

rrelaxed Makes the derivative zero at this end. 

rclamped Allows the caller to specify the derivative. The arguments pl-prime-x 
and pl-prime-y specify the derivative at the starting point, and are only 
used if cl is rclamped; likewise, pn-prime-x and pn-prime-y specify the 
derivative at the ending point, and are only used if c2 is rclamped. 

rcyclic Makes the derivative at the starting point and the ending point be equal. If 
cl is rcyclic then c2 is ignored. To draw a closed curve through n points, in 
addition to using rcyclic, you must pass in px and py with one more than n 
entries, since you must pass in the first point twice, once at the beginning 
and once at the end. 

ranti-cyclic Makes the derivative at the starting point be the negative of the 
derivative at the ending point. If cl is ranticyclic then c2 is ignored. 



(flavorrmethod rdraw-curve tvrgraphics-mixin) x-array y-array &optional end alu 

Method 

Draws a sequence of connected line segments. The x and y coordinates of the 
points at the ends of the segments are in the arrays x-array and y-array. The 
points between line segments are drawn exactly once and the point at the end of 
the last line is not drawn at all; this is especially useful when alu is tvralu-xor. 
The number of line segments drawn is 1 less than the length of the arrays, unless 
a nil is found in one of the arrays first in which case the lines stop being drawn. 
If end is specified it is used in place of the actual length of the arrays. 



(flavorrmethod rdraw-dashed-line tvrgraphics-mixin) from-x from-y to-x to-y &op- 
tional (alu tvrchar-alufj (dash-spacing 20) space-literally-p (offset 0) dash-length 

Method 

Draws a dashed line along the line lying between two points. All the dashes are 
the same length; all the spaces between the dashes are the same length. (The 
spaces, however, need not be the same length as the dashes). The spacing and 
lengths of the dashes are controlled by separate arguments. 

alu Controls how the pixels being drawn combine with pixels al- 

ready in the window. The default is the tvrchar-aluf for the 
window. 
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dash-spacing 



space-literally-p 



offset 
dash-length 



Specifies the distance from the beginning of one dash to the 
beginning of the next dash. It is expressed in pixels. The de- 
fault is 20. (The spacing between dashes is dash-spacing minus 
dash-length.) This specifies the "frequency" of the line. 

Controls what happens when the distance between the points, 
given the specified spacings, would not produce a full-size dash 
connected to the endpoint. 

The default value, nil, allows the size of dash-spacing to be ad- 
justed slightly so that the dashes are all of equal size and both 
endpoints look the same, as far as dash length goes. In this 
case, the dash-length is always exactly half of the dash-spacing; 
any values for offset and dash-length are ignored. 

The value t means to use dash-spacing exactly, with no adjust- 
ment. The endpoint might or might not have a dash connected 
to it, depending on the exact distances involved. 

Specifies a distance (in pixels) from the starting point (from-x, 
from-y) for the beginning of the first dash. This lets you con- 
trol the "phase" of the dashed line. 

Specifies the length of the line segments, in pixels. It must be 
less than dash-spacing. This lets you control the "duty cycle" of 
the line. The default is half the value of dash-spacing. 



You can make complex dashing by using :draw-dashed-line many times with space- 
literally-p as t. For example: 

(progn 
(dw : wi th-own-coordi nates (CL : xstandard-outputx) 
(send CL: xstandard-outputx 

' :draw-dashed-line 200. 200. tv:alu-ior 25. t 10.) 
(send CL: xstandard-outputx 

' :draw-dashed-line 200. 200. tv:alu-ior 25. t 15. 5.))) 

This gives you alternating long and short dashes. Because the default value, nil, 
for space-literally-p changes the spacing, this technique does not work well when 
space-literally-p is nil. 



graphics:draw-ellipse center-x center-y x-radius y-radius &key (inner-x-radius 0) 
(inner-y '-radius (/ (* graphics: :inner-x-radius graphics: :y-radius) graphics::x- 

radius)) (start-angle 0) (end-angle graphics:2pi) (clockwise nil) (join-to-path nil) 
(alu :draw) (pattern nil) (filled t) (stipple nil) (tile nil) (color nil) (gray-level 1) 
(opaque t) (mask nil) (mask-x 0) (mask-y 0) (thickness 0) (scale-thickness t) (line- 
end-shape :butt) (line-joint-shape :miter) (dashed nil) (dash-pattern '(10 10) ) (ini- 
tial-dash-phase 0) (draw-partial-dashes t) (scale-dashes nil) (stream *standard- 
output*) (return-presentation nil) (rotation 0) (scale 1) (scale-x 1) (scale-y 1) (transla- 
tion nil) (transform nil) Function 

Draws an ellipse, with 
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center-x The horizontal center of the ellipse. 

center-y The vertical center of the ellipse. 

x-radius The length of one of the ellipse's semi-axes; in the unrotated figure 
this axis is oriented horizontally. 

y-radius The length of the other semi-axis of the ellipse; in the unrotated 
figure this axis is oriented vertically. 

Of the listed keyword options, :inner-x-radius, :inner-y-radius, :start-angle, :end- 
angle, rclockwise, and :join-to-path are unique to graphicsrdraw-ellipse and docu- 
mented below. The remaining options are common to other drawing functions and 
documented separately: See the section "Keyword Options to Drawing Functions". 

:inner-x-radius SpecifiesthannemorizontaXunrotated^emi-axisof 

an elliptical ring figure; the default is 0. 

Example: 

(graphics :with-room-for-graphics (t 200) 

(graphics:with-graphics-translation (t 200 100) 
(graphics: draw-ell ipse 115 100 

: inner-x-radius 114 
: inner-y-radius 40) 
(graphics:draw-el 1 ipse 32 28))) 




:inner-y-radius SpecifiestheinneiverticaKunrotated)semi-axisoian 

elliptical ring figure. The default value is calculated so that the ra- 
tio of the two inner semi-axes equals the ratio of the two outer se- 
mi-axes. 

For an example, see the :inner-x-radius option. 

:start-angle Specifiestheangleinradiansatwhichdrawingofthe 

ellipse begins; the default is 0. This argument is interpreted the 
same way that the argument returned by the atan function is in- 
terpreted. Since in a window increasing y is down the screen, this 
means that angles with positive sines also point down the screen. 
(This is not the way the :draw-circular-arc message interprets an- 
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gles.) To avoid confusion, use a local coordinate system oriented in 
the direction you prefer, such as with graphics:with-room-for- 
graphics. 

Used in conjunction with the :end-angle option, arbitrary elliptical 
wedges can be drawn. The following example draws a semi-ellipse 
starting at 90 degrees and ending at 370 degrees: 

(graphics :with-room-for-graphics (t 200) 
(graphics: draw-ell ipse 200 100 100 35 

: start-angle (* .5 pi) 
: end-angle (* 1.5 pi))) 




:end-angle Specifiestheangleinradiansatwhichdrawingofthe 

circle ends; the default is graphics:2pi. Refer to the :start-angle 
option for a note about angle orientation. 

Used in conjunction with the :start-angle option, arbitrary elliptical 
wedges can be drawn. For an example, see the :start-angle option. 

rclockwise Booleanoptionspecifyingwhethertheellipseisdrawn 

in a clockwise or counterclockwise direction. The default is nil, 
counterclockwise. 

When graphicsrdraw-ellipse is being used as a standalone drawing 
function, this option only has a visible effect when less than a full 
ellipse is drawn, that is, when the :start-angle or :end-angle option 
is specified to some non-default value. The following example illus- 
trates this: 

(defun clockwise-ellipse (t-or-nil) 
(graphics:with-room-for-graphics (t 200) 
(graphics:draw-ellipse 200 100 100 35 

: end-angle (* .5 pi) 
:clockwise t-or-nil))) 



(clockwise-ellipse t) 
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(clockwise-ellipse nil) 




When graphicsrdraw-ellipse is being used as a path-drawing func- 
tion inside graphics:draw-path, this option affects path-winding 
rules. For more information: See the function graphics:draw-path. 
See also the :join-to-path option below. 

:join-to-path Specifythisoptiontwhenyouaremakinganelliptical 

arc part of a path outline, that is, using it in a graphics:draw-path 
function. This is to ensure that the arc joins the path properly to 
allow for filling without gaps. 

For an overview of graphicsrdraw-ellipse and related functions: See the section 
"Drawing Functions". 

(graphics :with-room-for-graphics (t 100) 
(graphics: draw-ell ipse 100 50 40 20 :filled nil) 
(graphics:draw-el 1 ipse 40 20 

: translation ' (300 50) 



rotation (* pi 1/4))) 








graphicsrdraw-ellipse-driver center-x center-y x-radius y-radius slice-function 

Function 



center-x The x-coordinate of the horizontal center of the ellipse. 
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center-y The y-coordinate of the vertical center of the ellipse. 

x-radius The length of the ellipse's horizontal semi-axis. 

y-radius The length of the vertical semi-axis of the ellipse. 

slice-function A function specifying how a rectangular slice of the el- 

lipse is to be drawn on a raster device and possibly specifying any 
other operations to be performed in conjunction with drawing the 
slice. This function must take four arguments: width, the width of 
the slice; height, its height; and x and y, the coordinates of the 
slice's location. A typical slice function is 

#' (lambda (width height x y) 

(send xstandard-outputx : draw-rectangle width height x y :draw)) 

Scan-converts the given ellipse, that is, computes the coordinates of the pixels that 
lie in the ellipse on a two-dimensional raster grid, and calls slice-function to draw 
these pixels. See the section "Graphics Drivers". 



graphics:draw-elliptical-ring-driver center-x center-y inner-x-radius inner-y-radius 
outer-x-radius outer-y-radius slice-function Function 

center-x The x-coordinate of the horizontal center of the elliptical ring. 

center-y The y-coordinate of the vertical center of the elliptical ring. 

inner-x-radius The length of the elliptical ring's inner horizontal se- 

mi-axis. 

inner-y-radius The length of the vertical inner semi-axis of the ellip- 

tical ring. 

outer-x-radius The length of the elliptical ring's outer horizontal se- 

mi-axis. 

outer-y-radius The length of the vertical outer semi-axis of the ellipti- 

cal ring. 

slice-function A function specifying how a rectangular slice of the el- 

liptical ring is to be drawn on a raster device and possibly specify- 
ing any other operations to be performed in conjunction with draw- 
ing the slice. This function must take four arguments: width, the 
width of the slice; height, its height; and x and y, the coordinates of 
the slice's location. A typical slice function is 

#' (lambda (width height x y) 

(send xstandard-outputx : draw-rectangle width height x y :draw)) 

Scan-converts the given elliptical ring, that is, computes the coordinates of the pix- 
els that lie on the elliptical ring on a two-dimensional raster grid, and calls slice- 
function to draw these pixels. See the section "Graphics Drivers". 
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(flavorrmethod :draw-filled-in-circle tv:graphics-mixin) center-x center-y radius 
&optional alu Method 

Draws a filled-in circle specified by its center and radius. The actual figure pro- 
duced is one pixel wider than radius. 



(flavorrmethod :draw-filled-in-sector tvrgraphics-mixin) center-x center-y radius 
theta-1 theta-2 &optional alu Method 

Draws a "triangular" section of a filled-in circle, bounded by an arc of the circle 
and the two radii at theta-1 and theta-2. These angles are in radians; an angle of 
zero is the positive-X direction, and angles increase counter-clockwise. Note: the 
interpretation of start-theta and end-theta are different for this message than it is 
for the graphicsrdraw-circle start-angle and end-angle. Also, the figure is not quite 
the same s the relevant portion produced by :draw-filled-in-circle. 



graphics:draw-glyph index font x y &key {alu :draw) (pattern nil) {stipple nil) {tile 
nil) {color nil) (gray-level 1) (opaque t) (mask nil) (mask-x 0) (mask-y 0) (stream 
*standard-output*) (return-presentation nil) (rotation 0) (scale 1) (scale-x 1) (scale-y 
1) (translation nil) (transform nil) Function 

Draws a figure referenced by a font array. The orientation of the glyph is unaf- 
fected by transforms. 

index The index into the font array. 

font The font. 

x The x-coordinate where the glyph is drawn (left edge). 

y The y-coordinate where the glyph is drawn (top edge). 

Example: 

(graphics :with-room-for-graphics (t 20) 

(graphics: draw-glyph (sys: char-sub index #\mouse: fat-double-horizontal -arrow) 

fonts:mouse 200 10)) 



To see the elements of a font, use the Show Font command. To see the list of 
loaded fonts, press the HELP key to the Show Font command. For more information 
on fonts, including information on how to create your own: See the section "Font 
Editor". 

Note that graphics:draw-glyph accepts relatively few of the keywords permitted 
by other drawing functions. All are documented separately: See the section "Key- 
word Options to Drawing Functions". 

For an overview of graphics:draw-glyph and related functions: See the section 
"Drawing Functions". 
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graphics:draw-image image left top &key {image-left 0) {image-top 0) {image-right 
nil) {image-bottom nil) {copy-image nil) {alu :draw) (pattern nil) {stipple nil) (ftZe 
nil) {color nil) (gray-level 1) (opaque t) (mask nil) (mask-x 0) (mask-y 0) (stream 
*standard-output*) (return-presentation nil) (rotation 0) (scaZe 1) (scale-x 1) (scale-y 
1) (translation nil) (transform nil) Function 

Draws a bit array as a graphics image. The orientation of the image is affected by 
transforms. 

image The bit array. This must be of "correct width" — that is, the width 
in bits must be a multiple of 32. 

Ze/£ The x-coordinate where drawing of the image begins. 

top The y-coordinate where drawing of the image begins. 

Of the listed keyword options, :image-left, :image-top, :image-right, rimage- 
bottom, and :copy-image are unique to graphics:draw-image and documented be- 
low. The remaining options are common to other drawing functions and document- 
ed separately: See the section "Keyword Options to Drawing Functions". 

:image-left Thefirstcolumninthebitarraytobeincludedinthe 

output image. 

:image-top The first row in the bit array to be included in the 

output image. 

:image-right Thelastcolumninthebitarraytobeincludedinthe 

output image. It defaults to the width of the image plus left. 

rimage-bottom Thelastrowinthebitarraytobeincludedintheout- 

put image. 

:copy-image Booleanoptionspecifyingwhethertomakeacopyof 

the image argument (bit array) and use the copy for drawing the 
image as opposed to using the original. The default is nil, meaning 
that the original is used. 

Specify : copy-image t if the bit array is re-used in your code but 
you want the image output by this particular operation to remain 
constant, that is, to always appear the same when the window is 
scrolled backwards and the image is redrawn. 



Example: 
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(defun draw-logo (&optional (stream xstandard-outputx) 
&key (scale 50)) 
(graphics :with-graphics-scale (stream scale) 
(graphics: draw-regular-polygon .75 .5 1.25 .5 4 

: stream stream : gray-level .25) 
(graphics:draw-regular-polygon 10 3 

: stream stream : gray-level .75) 
(graphics:draw-ci rcle 1.5 .5 .4 :stream stream 

: gray-level .5 : opaque t))) 

(graphics:with-room-for-graphics (t 50) 
(draw-logo)) 

(setq logo (graphics:with-output-to-bitmap (t) (draw-logo))) 

(graphics:with-room-for-graphics (t 50) 
(graphics:draw-image logo 0)) 



For an overview of graphics:draw-image and related functions: See the section 
"Drawing Functions". 



graphics:draw-line start-x start-y end-x end-y &key (draw -end-point t) (alu :draw) 
(pattern nil) (stipple nil) (tile nil) (color nil) (gray-level I) (opaque t) (mask nil) 
(mask-x 0) (mask-y 0) (thickness 0) (scale-thickness t) (line-end-shape :butt) (line- 
joint-shape rmiter) (dashed nil) (dash-pattern '(10 10)) (initial-dash-phase 0) (draw- 
partial-dashes t) (scale-dashes nil) (stream *standard-output*) (return-presentation 
nil) (rotation 0) (scale 1) (scale-x 1) (scale-y 1) (translation nil) (transform nil) 

Function 

Draws a line. 

start-x The x-coordinate of the starting point. 

start-y The y-coordinate of the starting point. 

end-x The x-coordinate of the ending point. 

end-y The y-coordinate of the ending point. 

All of the options are common to other drawing functions and documented sepa- 
rately: See the section "Keyword Options to Drawing Functions". 

For an overview of graphics:draw-line and related functions: See the section 
"Drawing Functions". 
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(graphics :with-room-for-graphics (t 100) 

(graphics:with-graphics-translation (t 50 50) 
(dotimes (r 8) 

(graphics :draw-l ine 25 :rotation (* graphics:2pi (/ r 8)))))) 




(flavorrmethod :draw-line tv:graphics-mixin) xl yl x2 y2 &optional alu (draw-end- 
point t) Method 

Draws a line on the window with endpoints (xl, yl) and (x2, y2). If draw-end-point 
is specified as nil, do not draw the last point. This is useful in cases such as xor- 
ing a polygon made up of several connected line segments. Note: :draw-line does 
not always clip properly. If correct clipping is important, use the function 
graphics:draw-line. See the section "Thin-Line Clipping". 



graphics:draw-line-driver xl yl x2 y2 draw-end-point slice-function Function 

Scan-converts the given line, that is, computes the coordinates of the pixels that 
lie near the line on a two-dimensional raster grid, and calls slice-function to draw 
these pixels. See the section "Graphics Drivers". 

xl The x-coordinate of the starting point of the line. This must be an 

integer. 

yl The y-coordinate of the starting point of the line. This must be an 

integer. 

x2 The x-coordinate of the ending point of the line. This must be an 

integer. 

y2 The y-coordinate of the ending point of the line. This must be an 

integer. 

draw-end-point A Boolean option specifying whether the end point of 

the line should be drawn. If draw-end-point is t, the pixel at 
<x2,y2> will be drawn; otherwise, it will not. 

slice-function A function specifying how a rectangular slice of the 

line is to be drawn on a raster device and possibly specifying any 
other operations to be performed in conjunction with drawing the 
slice. This function must take four arguments: width, the width of 
the slice; height, its height; and x and y, the coordinates of the 
slice's location. A typical slice function is 
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W (lambda 

(width height x y) 
(send xstandard-outputx 
height 
x y :draw)) 



: draw-rectangle width 



graphics:draw-line-to end-x end-y &key (alu :draw) (pattern nil) (stipple nil) (tile 
nil) (color nil) (gray-level 1) (opaque t) (mask nil) (mask-x 0) (mask-y 0) (thickness 
0) (scale-thickness t) (line-end-shape :butt) (line-joint-shape rmiter) (dashed nil) 
(dash-pattern #(10 10) ) (initial-dash-phase 0) (draw-partial-dashes t) (scale-dashes 
nil) (stream *standard-output*) (return-presentation nil) (rotation 0) (scale 1) 
(scale-x 1) (scale-y 1) (translation nil) (transform nil) Function 

Draws a line from the current position of the graphics cursor to a specified point. 
When done, the graphics cursor is moved to the point. 

end-x The x-coordinate of the end-point. 
end-y The y-coordinate of the end-point. 

This function is intended primarily for path building, that is, within path-drawing 
functions supplied to graphics:draw-path or graphics:with-clipping-path. For ex- 
ample uses: See the function graphics:draw-path. 

The listed keyword options are common to all drawing functions and documented 
separately: See the section "Keyword Options to Drawing Functions". 

For an overview of graphics:draw-line-to and related functions: See the section 
"Drawing Functions". 

(graphics:with-room-for-graphics (t 100) 
(graphics:with-graphics-translation (t 50 50) 
(graphics:with-graphics-scale (t 40) 
(graphics:drawing-path (t :filled nil : scale-thickness nil) 
(graphics:set-current-position 0) 
(loop for r below 10 by 1/10 do 

(graphics:draw-l ine-to r (sin r))))))) 




graphics:draw-lines points &key (closed nil) (Join-to-path nil) (alu :draw) (pattern 
nil) (stipple nil) (tile nil) (color nil) (gray-level 1) (opaque t) (mask nil) (mask-x 0) 
(mask-y 0) (thickness 0) (scale-thickness t) (line-end-shape :butt) (line-joint-shape 
rmiter) (dashed nil) (dash-pattern '(10 10) ) (initial-dash-phase 0) (draw-partial- 
dashes t) (scale-dashes nil) (stream *standard-output*) (return-presentation nil) (ro- 
tation 0) (scale 1) (scale-x 1) (scale-y 1) (translation nil) (transform nil) Function 
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Draws a connected series of line segments. 

points A sequence of points in the form {xl yl x2 y2 ... xn yn). 

Of the listed keyword options, rclosed and :join-path-to are documented below. 
The remaining options are common to other drawing functions and documented 
separately: See the section "Keyword Options to Drawing Functions". 

rclosed Boolean option specifying whether the points are to form a closed 

figure, that is, whether to draw a line connecting the last point 
specified with the first; the default is nil. 

(graphics :with-room-for-graphics (t 100) 

(graphics: draw-lines '(0 10 20 20 30 30 80 40 20 50 0) :closed t)) 




:join-to-path Specify this option t when you are making the line 

series part of a path outline, that is, using it in a graphicsrdraw- 
path function. This is to ensure that the multiple-line segment joins 
the path properly to allow for filling without gaps. 

For an overview of graphicsrdraw-lines and related functions: See the section 
"Drawing Functions". 

(graphics :with-room-for-graphics (t 100) 

(graphics:draw-lines '(0 10 20 20 30 30 80 40 20 50 0) :thickness 2)) 




(flavorrmethod rdraw-lines tvrgraphics-mixin) alu xO yO xl yl ... xn yn Method 

Draws n lines on the screen, the first with endpoints (xO, yO) and {xl, yl), the sec- 
ond with endpoints {xl, yl) and {x2, y2), and so on. The points between lines are 
drawn exactly once and the last endpoint, at {xn, yn), is not drawn. 



graphics:draw-oval center-x center-y x-radius y-radius &rest args &key (.-filled t) 
&allow-other-keys Function 

Draws an oval, that is, a "race-track" shape, centered on {center-x center-y): if x-ra- 
dius or y-radius is 0, draws a circle with the specified non-zero radius; otherwise, 
draws the figure that results from drawing a rectangle with dimensions x-radius 
and y-radius and then replacing the two short sides with semicircular arc of appro- 
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priate size. Example: 

(graphics :with-room-for-graphics (t 100) 

(graphics: draw-oval 100 50 40 20 : filled nil)) 



:draw-partial-dashes Option 

Boolean option specifying whether a partial dash is drawn at the end of a 
dashed line so that it reaches its specified end-point. The default is t: dashes 
are drawn with the specified numbers of pixels on and off until the endpoint 
is reached, at which point drawing stops wherever in the pattern you happen 
to be. 

If you specify nil for this option, the drawing routine will adjust the spacing 
of the dashes so that the lines ends on a "dash." In the simple case — that 
is, with only a single pair of numbers in the dash pattern — a dash is a solid 
line of (on) pixels, so both ends of such a line are drawn. For example, try 
these: 

(graphics:with-room-for-graphics (t 10) 

(graphics:draw-l ine 3 200 3 :dashed t : dash-pattern #(20 15) 

: draw-partial -dashes t) 
(graphics:draw-l ine -3 200 -3 :dashed t 

:dash-pattern #(20 15) : draw-partial -dashes nil) 
(graphics:draw-line 200 -3 200 3)) 



(graphics:with-room-for-graphics (t 250) 
(let ((zoom 5)) 

(dolist (partial ' (t nil)) 

(graphics:with-graphics-translation (t (if partial (* 25 zoom) 0)) 
(dotimes (i 20) 

(let ((y (* (- 19 i) zoom))) 

(graphics:draw-l ine y (* i 4 zoom) y 
: dashed T 

:dash-pattern #(20 15) 
: draw-partial -dashes partial) 
(graphics:draw-l ine (- y 1) (* i 4 zoom) (- y 1)))))))) 

For more complicated dash patterns, a dash is considered to be a solid line 
somewhere in the pattern: you will have to experiment to determine the exact 
result of using the option. 

This option is not operable if the rdashed option to the drawing function is 
nil. 
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Some hardcopy devices, most notably PostScript printers, cannot adjust the 
spacing of the dashes; that is, they will draw partial dashes even if you speci- 
fy :draw-partial-dashes nil. 



graphics:draw-path path-function &key {winding-rule :non-zero) (alu :draw) (pat- 
tern nil) (filled t) (stipple nil) (tile nil) (color nil) (gray-level 1) (opaque t) (mask 
nil) (mask-x 0) (mask-y 0) (thickness 0) (scale-thickness t) (line-end-shape :butt) 
(line-joint-shape rmiter) (dashed nil) (dash-pattern #(10 10) ) (initial-dash-phase 0) 
(draw-partial-dashes t) (scale-dashes nil) (stream *standard-output*) (return- 
presentation nil) (rotation 0) (scale 1) (scale-x 1) (scale-y 1) (translation nil) (trans- 
form nil) Function 

Draws a finable figure whose outline is specified by a user-supplied path function. 

path-function A drawing function creating the outline of a figure, 

that is, a path. This path can be arbitrarily complex, contain 
straight- and curved-line segments, and include more than one 
closed subpath. 

Of the listed keyword options, :winding-rule is unique to graphics:draw-path and 
documented below. The remaining options are common to all drawing functions 
and documented separately: See the section "Keyword Options to Drawing Func- 
tions". 

:winding-rule Controls filling of the region outlined by the path- 

drawing function. Two values are possible: 

:non-zeroA point is within the area to be filled if a ray from the 
point to infinity crosses an unequal number of left-to-right 
and right-to-left path segments. 

:odd-evenA point is within the area to be filled if a ray from the 
point to infinity crosses the path an odd number of times. 

The :non-zero rule is generally the more robust in terms of filling 
complex shapes completely. The :odd-even rule is useful mostly for 
special effects. See the path-drawing-examples function in the "Ex- 
amples" section below for winding-rule effects on the filling of a 
star-shaped path. 

Note that the direction in which ellipses and circles are drawn, 
when part of a path-drawing function, affects filling using the :non- 
zero rule. This is demonstrated in the overlapping-circles function 
below. 
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(graphics :with-room-for-graphics (t 100) 

(graphics: drawing-path () 
(graphics :draw-ci rcle 50 50 40 :filled nil) 
(graphics:draw-ci rcle 50 50 20 :filled nil)) 

(graphics: graphics-translate 100 0) 

(graphics:drawing-path (t :winding-rule :odd-even) 
(graphics:draw-ci rcle 50 50 40 :filled nil) 
(graphics:draw-ci rcle 50 50 20 :filled nil)) 

(graphics:graphics-translate 100 0) 

(graphics:drawing-path () 
(graphics:draw-ci rcle 50 50 40 :filled nil) 
(graphics:draw-ci rcle 50 50 20 :filled nil :clockwise t)) 

(graphics:graphics-translate 100 0) 

(graphics:drawing-path (t :winding-rule :odd-even) 
(graphics:draw-ci rcle 50 50 40 :filled nil) 
(graphics:draw-ci rcle 50 50 20 :filled nil :clockwise t))) 

Examples: 

;;; The following three functions are "drawers" to be 
;;; called by the function "path-drawing-examples". 

(defun star-drawer (xstandard-outputx) 

(graphics:set-current-position 0) 

(dotimes (i 4) 

(graphics:draw-l ine-to 1 0) 

(graphics: graphics-origin-to-cur rent-posit ion) 

(graphics:graphics-rotate (float (x -4/5 pi) 0.0))) 

(graphics: close-path)) 
(defun bz-drawer (xstandard-outputx) 

(graphics:set-current-position 0) 

(graphics:draw-bezier-curve-to 1 1 1/2 3/2 3/4 -1/2) 

(graphics:draw-l ine-to 1 -1) 



Page 1539 



(graphi 
(defun wi 
(graphi 
(graphi 
(graphi 
(graphi 
(graphi 
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(graphi 
(graphi 
(graphi 
(graphi 
(graphi 
(graphi 
(graphi 
(graphi 
(graphi 
(graphi 
(graphi 
(graphi 



cs: close-path)) 

dget-drawer (xstandard-outputx) 

cs:graphics-scale 1/10) 

cs: set-current-position 1 0) 



cs:draw- 
cs:draw- 
cs:draw- 
cs:draw- 
cs:draw- 
cs:draw- 
cs:draw- 
cs:draw- 
cs:draw- 
cs:draw- 
cs:draw- 
cs:draw- 
cs:draw- 
cs:draw- 
cs:draw- 



ine-to 2 0) 

ine-to 2 1) 

ine-to 7 1) 

ine-to 7 0) 

ine-to 8 0) 

ine-to 8 3) 

ine-to 7 3) 

ine-to 7 2) 

ine-to 5 2) 

ine-to 5 8) 

ine-to 4 8) 

ine-to 4 2) 

ine-to 2 2) 

ine-to 2 3) 

ine-to 1 3) 



cs: close-path)) 



This function applies graphics: draw-path to one 
of the drawers (above drawing functions). You 
specify which drawer with the :drawer keyword, 
one of tf'star-drawer (the default), tf'bz-drawer, 
or tf'widget-drawer . You can also provide any 
other keywords recognized by graphics:draw-path; 
for example, try :filled t and :winding-rule 
: odd-even (versus. : non-zero) on the star-drawer. 
(For another winding rule example, see the 
overlapping-ci rcles function, below.) 



(defun path-drawing-examples (&rest args 

&key (scale 100) 
(rotation 0) 
(drawer tf'star-drawer) 
&al 1 ow-other-keys) 
(graphics:with-room-for-graphics (t 200) 

(graphics:with-graphics-translation (t 100 100) 
(graphics:with-graphics-scale (t scale) 

(graphics:with-graphics-rotation (t rotation) 
(si :with-rem-keywords 
(some-args args 

' ( :scale :drawer)) 
(apply #'graphics:draw-path 

drawer some-args))))))) 
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; ; ; How circles and ellipses are drawn, that is, 
;;; whether clockwise or counterclockwise, affects 
;;; path filling via the :non-zero winding rule. 

(defun overlapping-ci rcles (clockwise-p winding-rule) 
(graphics:with-room-for-graphics (t 200) 
(graphics: draw-path 
(lambda (s) 

(graphics:draw-ci rcle 100 100 75 

: stream s 
:filled nil 
:clockwise 
clockwise-p) 
(graphics:draw-ci rcle 200 100 75 

: stream s 
:filled nil)) 
: translation ' (100 0) 
: filled t 
: gray-level 4/5 
:winding-rule winding-rule))) 

For an overview of graphics:draw-path and related functions: See the section 
"Drawing Functions". 



graphicsrdraw-pattern left top pattern &key (.stream *standard-output*J (:alu 
rdrawj .-right .-bottom (.-pattern-left 0) (-pattern-top 0) .-copy-pattern Function 

Included only for compatibility with Genera 7.1. If you are writing new code, use 
the function graphics:draw-image for drawing images and the rstipple option to 
graphicsrdraw-rectangle for repeating patterns. 



graphics:draw-point x y &key (alu :draw) (pattern nil) (stipple nil) (tile nil) (color 
nil) (gray-level 1) (opaque t) (mask nil) (mask-x 0) (mask-y 0) (stream *standard- 
output*) (return-presentation nil) (rotation 0) (scale 1) (scale-x 1) (scale-y 1) (transla- 
tion nil) (transform nil) Function 

Draws a point. The single-pixel size of the point is unaffected by transforms. Note 
that if you have a lot of points to draw to a dynamic window, it is better to draw 
them to a bitmap first and then to the screen, since this will help reduce the size 
of the output history. 
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(multiple-value-bind (bitmap x y) 
(graphics :with-output-to-bitmap () 
(dotimes (i 100) 
(graphics:draw-point (random 50) (random 50) :alu :flip))) 
(graphics:with-room-for-graphics (t 60) 

(graphics:draw-image bitmap (+ x 50) (- y 50) :scale-y -1))) 



x The point's x-coordinate. 

y The point's y-coordinate. 

All of the options are common to other drawing functions and documented sepa- 
rately: See the section "Keyword Options to Drawing Functions". 

For an overview of graphics:draw-point and related functions: See the section 
"Drawing Functions". 

(flavorrmethod :draw-point tv:graphics-mixin) x y &optional alu value Method 

Draws value into the picture element at the specified coordinates, combining it 
with the previous contents according to the specified alu function {value is the 
first argument to the operation, and the previous contents is the second argu- 
ment.) value should be or 1 on a black-and-white TV. Clipping is performed; that 
is, this message will have no effect if the coordinates are outside the window, val- 
ue defaults to -1, that is, a number with all ones. 



graphicsrdraw-polygon points &key (points-are-convex-p nil) &allow-other-keys (alu 
:draw) (pattern nil) (filled t) (stipple nil) (tile nil) (color nil) (gray-level 1) (opaque 
t) (mask nil) (mask-x 0) (mask-y 0) (thickness 0) (scale-thickness t) (line-end-shape 
:butt) (line-joint-shape rmiter) (dashed nil) (dash-pattern '(10 10) ) (initial-dash- 
phase 0) (draw-partial-dashes t) (scale-dashes nil) (stream *standard-output*) (re- 
turn-presentation nil) (rotation 0) (scale 1) (scale-x 1) (scale-y 1) (translation nil) 
(transform nil) Function 

Draws a polygon connecting a set of points. 

points A sequence of points in the form (xl yl x2 y2 ... xn yn); these form 
the points of the polygon. 

Of the listed keyword options, :points-are-convex-p is unique to graphicsrdraw- 
polygon and documented below. The remaining options are common to other draw- 
ing functions and documented separately: See the section "Keyword Options to 
Drawing Functions". 

:points-are-convex-p Boolearoptiorepecifyingvhetheithepomfcdescribea 

convex polygon; the default is nil. If t, an algorithm more efficient 
for drawing convex polygons, as opposed to any polygon, is used. 
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For an overview of graphicsrdraw-polygon and related functions: See the section 
"Drawing Functions". 

(graphics :with-room-for-graphics (t 100) 

(graphics: draw-polygon '(0 100 100 100 100 0))) 




graphicsrdraw-rectangle left top right bottom &key (alu :draw) (pattern nil) (filled 
t) (stipple nil) (tile nil) (color nil) (gray-level 1) (opaque t) (mask nil) (mask-x 0) 
(mask-y 0) (thickness 0) (scale-thickness t) (line-end-shape :butt) (line-joint-shape 
rmiter) (dashed nil) (dash-pattern '(10 10) ) (initial-dash-phase 0) (draw-partial- 
dashes t) (scale-dashes nil) (stream *standard-output*) (return-presentation nil) (ro- 
tation 0) (scale 1) (scale-x 1) (scale-y 1) (translation nil) (transform nil) Function 

Draws a rectangle. 

Ze/£ The x-coordinate of the left side of the rectangle, 

top The y-coordinate of the top side of the rectangle. 

right The x-coordinate of the right side of the rectangle. 

bottom The y-coordinate of the bottom side of the rectangle. 

The listed keyword options are common to other drawing functions and document- 
ed separately: See the section "Keyword Options to Drawing Functions". 

For an overview of graphicsrdraw-rectangle and related functions: See the section 
"Drawing Functions". 

(graphics :with-room-for-graphics (t 100) 

(graphics: draw-rectangle 60 30 140 70 :filled nil) 

(graphics:draw-rectangle -40 -20 40 20 : translation '(300 50) : rotation (* pi 1/4))) 




(flavorrmethod : draw-rectangle tvrsheet) width height x y &optional alu Method 

Draws a filled-in rectangle with dimensions width by height on the window with its 
upper left corner at coordinates (x, y). 
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graphicsrdraw-regular-polygon start-x start-y end-x end-y number-of-sides &key 
{handedness :left) &allow-other-keys (alu :draw) (pattern nil) (filled t) (stipple nil) 
(tile nil) (color nil) (gray-level 1) (opaque t) (mask nil) (mask-x 0) (mask-y 0) (thick- 
ness 0) (scale-thickness t) (line-end-shape :butt) (line-joint-shape rmiter) (dashed nil) 
(dash-pattern '(10 10) ) (initial-dash-phase 0) (draw-partial-dashes t) (scale-dashes 
nil) (stream *standard-output*) (return-presentation nil) (rotation 0) (scale 1) 
(scale-x 1) (scale-y 1) (translation nil) (transform nil) Function 

Given the starting and ending coordinates for a single side and the number of 
sides, draws a regular polygon. 

start-x The x-coordinate of the starting point for side 1. 
start-y The y-coordinate of the starting point for side 1. 
end-x The x-coordinate of the ending point for side 1. 
end-y The y-coordinate of the ending point for side 1. 
number-of-sides The total number of sides. 

Of the listed keyword options, rhandedness is unique to graphicsrdraw-regular- 
polygon and documented below. The remaining options are common to other draw- 
ing functions and documented separately: See the section "Keyword Options to 
Drawing Functions". 

rhandedness Specifieswhetherthepolygonisdrawntotherleftor 

rright of side 1. The default is rleft, meaning that, if you were lo- 
cated at (start-x start-y) and facing (end-x end-y), the polygon would 
be drawn to your left. 

For an overview of graphicsrdraw-regular-polygon and related functions: See the 
section "Drawing Functions". 

(graphics :with-room-for-graphics (t 100) 

(graphics: draw-regular-polygon 100 140 7 :filled nil :thickness 2)) 




(flavorrmethod r draw-regular-polygon tvrgraphics-mixin) xl yl x2 y2 n &optional 
alu Method 

Draws a filled-in, closed, convex, regular polygon of (abs n) sides, where the line 
from (xl, yl) to (x2, y2) is one of the sides. If n is positive, the interior of the poly- 
gon is on the right-hand side of the edge (that is, if you were walking from (xl, 
yl) to (x2, y2), you would see the interior of the polygon on your right-hand side; 
this does not mean "toward the right-hand edge of the window"). 



Page 1544 



graphicsrdraw-string string x y &key (:attachment-y rbaseline) (:attachment-x rleft) 
(:toward-x (1+ graphicsrrstart-x)J (:toward-y graphicsrrstart-y) :stretch-p -.character- 
style :record-as-text (:alu rdrawj .-pattern .stipple stile .-color (.-gray-level I) (-.opaque t) 
.-mask (:mask-x 0) (:mask-y 0) (stream *standard-output*) .-return-presentation (-ro- 
tation 0) (scale 1) (scale-x I) (scale-y I) .-translation .-transform Function 

Draws a character string. 

string The string. 

x The x-coordinate where drawing of the string begins (see the 

:attachment-x option below). 

y The y-coordinate where drawing of the string begins (see the 

:attachment-y option below). 

Of the listed keyword options, :attachment-x, :attachment-y, :toward-x, 
:toward-y, :stretch-p, and :character-style are unique to graphicsrdraw-string 

and documented below. The remaining options are common to other drawing func- 
tions and documented separately: See the section "Keyword Options to Drawing 
Functions". 

Note that coordinate system options (rrotation, rscale, and so on) affect the posi- 
tion of the character string (baseline) but not the size or orientation of the indi- 
vidual characters. Character size is controlled by the rcharacter-style option and 
the orientation of the individual glyphs is always upright. If you want the charac- 
ter string, including glyphs, to respond similarly to other graphic images, use the 
graphicsrdraw-string-image function. 

:attachment-x Specifiesthestringattachmentpointtothexcoordi- 

nate: 

rleft The left edge of the first character is positioned at x. 

This is the default. 

rright The right edge of the last character is positioned at x. 

reenter The horizontal center of the string is positioned at x. 

(graphics :with-room-for-graphics (t 100) 
(graphics: draw-arrow 40 40) 
(graphics: draw-string "string" 40 40 :attachment-x :center)) 



string 



:attachment-y Specifiesthestringattachmentpointtotheycoordi- 

nate: 
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rbaseline The baseline of the string is positioned at y. This is the 
default. 

rbottom The bottom of the string is positioned at y. 

:top The top of the string is positioned at y. 

reenter The vertical center of the string is positioned at y. 

The following example illustrates the differences among these pos- 
sibilities: 

(graphics :with-room-for-graphics (t 150) 

(graphics: draw-string " :basel ine-yy" 10 50 

:attachment-y : baseline 

: character-style 

'(nil nil : very-large)) 

(graphics :draw-l ine 10 50 155 50) 

(graphics: draw-string " :bottom-yy" 200 50 

:attachment-y : bottom 

: character-style 

'(nil : roman : very-large)) 

(graphics:draw-line 200 50 320 50) 

(graphics: draw-string ":top-yy" 365 50 

:attachment-y :top 

: character-style 

'(nil nil : very-large)) 

(graphics:draw-l ine 365 50 450 50) 

(graphics:draw-string ":center-yy" 500 50 

:attachment-y : center 

: character-style 

'(nil nil : very-large)) 

(graphics:draw-line 500 50 620 50)) 



basPl inp-yy :bottom-yy -cent 

: top-yy 



rtoward-xThex-coordinatetowardwhichthestringisdrawn.Thedefaultval- 

ue is one greater than the starting x-coordinate, meaning that the 
string is drawn to the right; its deviation from the horizontal is de- 
termined by the :toward-y option. 

rtoward-yThey-coordinatetowardwhichthestringisdrawn.Thedefaultval- 

ue is equal to the starting y-coordinate, meaning that the string is 
drawn horizontally. 
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(graphics :with-room-for-graphics (t 100) 

(graphics: draw-string "string" :toward-x 100 :toward-y 50)) 



rstretch-pBooleanoptionspecifyingwhetherthecharactersarespacedevenly 

between the starting (start-x start-y) and ending (:toward-x <end-x> 
:toward-y <end-y>) coordinates. 

If the space provided is greater than that required by the default 
spacing between characters of the given style, then additional spac- 
ing is inserted; the string is stretched. If the space is less than that 
required by the default spacing, space is eliminated; the string is 
compressed. 

The default is nil, meaning that the default spacing for the charac- 
ter style in question is used, regardless of the distance between the 
starting and ending coordinates. 

(graphics:with-room-for-graphics (t 100) 
(graphics:draw-string "normal" 40 :toward-x 200) 
(graphics:draw-string "stretched" 20 :toward-x 200 :stretch-p t)) 

normal 



:character-style Specifies a character style for the string. Merging 

against the default character style for the output stream is support- 
ed. 

(graphics:with-room-for-graphics (t 30) 

(graphics:draw-string "string" 10 10 : character-style '(:dutch nil nil))) 
string 

For an overview of graphicsrdraw-string and related functions: See the section 
"Drawing Functions". 

(graphics:with-room-for-graphics (t 100) 
(graphics:draw-string "right" 0) 

(graphics: draw-string "down" 50 :toward-x :toward-y 0) 
(graphics:draw-string "away" 10 10 :toward-x 50 :toward-y 50 :stretch-p t)) 



right 
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(flavorrmethod :draw-string tv:graphics-mixin) string from-x from-y &optional (to- 
ward-x (1+ tv:from-x)) (toward-y tv:from-y) (stretch-p nil) character-style (alu 
tv:char-aluf) Method 

Draws a character string between two points. 

The left baseline point of each character lies on the line between the two points 
defined by from-x, from-y and toward-x, toward-y. 

The string is always written from left to right, starting at the leftmost point, re- 
gardless of whether that is the first point or the second point. When the string is 
longer than the line between the points, the full string appears anyhow. 

toward-x, toward-y Controls the direction in which printing takes place. The de- 
fault values specify ordinary horizontal output. 

(send (tv:window-under-mouse) ' : draw-string 
"hi there" 600 50) 

stretch-p Controls the spacing of the characters. When it is nil (the 

default), the characters appear literally, with no change to 
the spacing. Otherwise, the distance between the characters 
is adjusted so that the string starts and ends as close to the 
two points as possible. 

character-style Specifies the character style to use. The default is the default 

character style for the window, or that specified by a charac- 
ter style macro: See the section "Character Environment Fa- 
cilities". 

alu Controls how the pixels being drawn combine with pixels al- 

ready in the window. The default is the tv:char-aluf for the 
window. 

This message is useful for placing text at absolute screen positions (as opposed to 
treating the window as a stream), for labelling graphs, or for putting text into 
pictures. 



graphics:draw-string-image string x y &key (attachment-y rbaseline) (attachment-x 
:left) (character-style nil) (character-size nil) string-width (scale-down-allowed t) (alu 
:draw) (pattern nil) (stipple nil) (tile nil) (color nil) (gray-level 1) (opaque t) (mask 
nil) (mask-x 0) (mask-y 0) (stream *standard-output*) (return-presentation nil) (ro- 
tation 0) (scale 1) (scale-x 1) (scale-y 1) (translation nil) (transform nil) Function 

Draws a character string as a graphics image. This enables the string to be ma- 
nipulated in the same manner that other images can be manipulated. For example, 
the string can be scaled or rotated as a unit. This allows you to draw slanted or 
tilted character strings. This is unlike strings generated by graphicsrdraw-string, 
in which only the position of the baseline is affected by coordinate system changes; 
the character glyphs remain the same. Note that graphics:draw-string-image 
draws the image upside down relative to the character glyphs. You can use 
graphics:with-room-for-graphics around graphics:draw-string-image or transform 
coordinates to get the character glyphs oriented the way you want it. 
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string The string. 

x The x-coordinate where drawing of the string begins (see the 

:attachment-x option below). 

y The y-coordinate where drawing of the string begins (see the 

:attachment-y option below). 

Of the listed keyword options, :attachment-x, :attachment-y, :character-style, 
:character-size, :string-width, and :scale-down-allowed are unique to 
graphics:draw-string-image and documented below. The remaining options are 
common to other drawing functions and documented separately: See the section 
"Keyword Options to Drawing Functions". Example: 

(graphics :with-room-for-graphics (t 100) 
(graphics: draw-string-image "normal" 0) 
(graphics:draw-string-image "sideways" 10 

translation '(50 0) :rotation (/ pi 2))) 



:attachment-x Specifiesthestringattachmentpointtothexcoordi- 

nate: 

:left The left edge of the first character is positioned at x. 

This is the default. 

rright The right edge of the last character is positioned at x. 

reenter The horizontal center of the string is positioned at x. 

The position in the string is as viewed in the user coordinate sys- 
tem, so if the string is being rotated, it may not be that point of 
the string on the screen. 

(graphics:with-room-for-graphics (t 100) 
(graphics:draw-arrow 40 : rotation (/ pi 4)) 
(graphics:draw-string-image "string" 40 

: rotation (/ pi 4) :attachment-x : center)) 



:attachment-y Specifiesthestringattachmentpointtotheycoordi- 

nate, one of the following: 

rbaseline The baseline of the string is positioned at y. This is the 
default. 
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rbottom The bottom of the string is positioned at y. 

:top The top of the string is positioned at y. 

reenter The vertical center of the string is positioned at y. 

For an example showing the differences among the different attach- 
ment points: See the function graphicsrdraw-string. In particular, 
look at the :attachment-y option. 

rcharacter-style Specifies the character style for the string. Merging 

against the default character style for the output stream is support- 
ed. 

If the :character-size option is specified, it overrides the size com- 
ponent of the rcharacter-style specification. 

:character-size Specifiesanumbercontrollingcharactersize.Thede- 

fault is nil, meaning that character size is determined by the size 
component of the output character style. 

If you use this option, the number specified is scaled and a font 
chosen with the same family and face as the output character style, 
but with a size as close as possible to that desired. If you supply 
this option with a large number and none of the predefined fonts 
are big enough, then the largest font available is scaled up, pixel by 
pixel, to achieve the desired size. 

To see the effects of this option, try calling the following with the 
string of your choice and various numbers in the 10 to 100 range 
(you are not limited to this range, however). The horizontal lines 
are 20 pixels apart, except for the first three which are 10 pixels 
apart. 

(defun string-size (string size) 

(graphics:with-room-for-graphics (t 100) 
(graphics:draw-string-image string 

: character-size size) 
(graphics:draw-l ine 300 :thickness 2) 
(graphics:draw-line 10 300 10) 
(graphics:draw-line 20 300 20) 
(graphics:draw-line 40 300 40) 
(graphics:draw-l ine 60 300 60) 
(graphics:draw-line 80 300 80) 
(graphics:draw-line 100 300 100))) 



(string-size "string" 10) 
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atxj n c 



(string-size "string" 30) 



S r r i n q 



(string-size "string" 60) 



sr.ri ng 



:string-width Specifies the final width of the string drawn. The 

image is scaled if necessary so that this width is attained. The 
spacing within characters is adjusted to make up for differences be- 
tween the font sizes available and the desired size. When used in 
conjunction with the :character-size option, a string can be drawn 
of exactly the desired size using the closest available font. 

(graphics:with-room-for-graphics (t 100) 
(loop for scale in '(1/2 1 2 4) do 

(graphics:draw-string-image "string" 10 

: scale scale 
:string-width 100 



character-size 10))) 



1 



n 



n 



:scale-down-allowed A Boolean option specifying when true, the default, 
that the string image may be scaled down, that is, drawn with a 
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scale factor less than one, if necessary to accommodate the require- 
ment of :string-width. If :scale-down-allowed is t, the resulting 
string will probabaly not be readable is :string-width is small; if it 
is nil, the string will exceed the size constraint. 

For an overview of graphics:draw-string-image and related functions: See the sec- 
tion "Drawing Functions". 



graphicsrdraw-triangle xl yl x2 y2 x3 y3 &key (alu :draw) (pattern nil) (filled t) 
(stipple nil) (tile nil) (color nil) (gray-level 1) (opaque t) (mask nil) (mask-x 0) 
(mask-y 0) (thickness 0) (scale-thickness t) (line-end-shape :butt) (line-joint-shape 
rmiter) (dashed nil) (dash-pattern '(10 10) ) (initial-dash-phase 0) (draw-partial- 
dashes t) (scale-dashes nil) (stream *standard-output*) (return-presentation nil) (ro- 
tation 0) (scale 1) (scale-x 1) (scale-y 1) (translation nil) (transform nil) Function 

Draws a triangle. 

xl The x-coordinate of the first point of the triangle. 

yl The y-coordinate of the first point of the triangle. 

x2 The x-coordinate of the second point of the triangle. 

y2 The y-coordinate of the second point of the triangle. 

x3 The x-coordinate of the third point of the triangle. 

y3 The y-coordinate of the third point of the triangle. 

The listed keyword options are common to other drawing functions and document- 
ed separately: See the section "Keyword Options to Drawing Functions". 

For an overview of graphicsrdraw-triangle and related functions: See the section 
"Drawing Functions". 

(graphics :with-room-for-graphics (t 100) 
(graphics: draw-triangle 120 40 75 : filled nil)) 




(flavorrmethod : draw- triangle tvrgraphics-mixin) xl yl x2 y2 x3 y3 &optional alu 

Method 

Draws a filled-in triangle with its corners at (xl, yl), (x2, y2), and (x3, y3). 
graphicsrdraw-triangle-driver xl yl x2 y2 x3 y3 slice-function Function 
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Scan-converts the given triangle, that is, computes the coordinates of the pixels 
that lie in the triangle on a two-dimensional raster grid, and calls slice-function to 
draw these pixels. See the section "Graphics Drivers". 

xl The x-coordinate of the first vertex of the triangle. This must be an 

integer. 

yl The y-coordinate of the first vertex of the triangle. This must be an 

integer. 

x2 The x-coordinate of the second vertex of the triangle. This must be 

an integer. 

y2 The y-coordinate of the second vertex of the triangle. This must be 

an integer. 

x3 The x-coordinate of the third vertex of the triangle. This must be 

an integer. 

y3 The y-coordinate of the third vertex of the triangle. This must be 

an integer. 

slice-function A function specifying how a rectangular slice of the 

triangle is to be drawn on a raster device and possibly specifying 
any other operations to be performed in conjunction with drawing 
the slice. This function must take four arguments: width, the width 
of the slice; height, its height; and x and y, the coordinates of the 
slice's location. A typical slice function is 

#' (lambda (width height x y) 

(send xstandard-outputx : draw-rectangle width height x y :draw)) 



graphicsrdraw-unfilled-circle-driver center-x center-y radius point-function &option- 
al (separate-quadrants nil) Function 

Scan-converts the outline of the circle, that is, computes the coordinates of the 
pixels that lie near the outline of the circle on a two-dimensional raster grid, and 
calls point-function to draw these pixels. See the section "Graphics Drivers". 

center-x The x-coordinate for the center of the circle. 

center-y The y-coordinate for the center of the circle. 

radius The radius of the circle. 

point-function A function specifying how a point on the circle is to be 

drawn on a raster device and possibly specifying any other opera- 
tions to be performed in conjunction with drawing the point. This 
function must take two arguments, x and y, the point's coordinates. 
A point function could be, for example, 

(graphics:draw-point x y) 
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separate-quadrants A Boolean option specifying whether all the points in a 
quadrant should be drawn before the another quadrant is started. 
When separate-quadrants is t, each quadrant's points are drawn in 
turn, making it possible for the points to be a connected set of line 
segments. This is necessary if the circle is to be part of a path. 
When the default, nil, is taken, the unfilled circle is drawn with 
slices, possibly overlapping the axes, which are converted to points, 
by calling draw-circular-ring-driver with appropriate radii. 



graphicsrdraw-unfilled-ellipse-driver center-x center-y x-radius y-radius point- 
function &optional {separate-quadrants nil) Function 

Scan-converts the outline of the ellipse, that is, computes the coordinates of the 
pixels that lie near the outline of the ellipse on a two-dimensional raster grid, and 
calls point-function to draw these pixels. See the section "Graphics Drivers". 

center-x The x-coordinate for the horizontal center of the ellipse. 

center-y The y-coordinate for the vertical center of the ellipse. 

x-radius The length of one of the ellipse's semi-axes; in the unrotated figure 
this axis is oriented horizontally. 

y-radius The length of the other semi-axis of the ellipse; in the unrotated 
figure this axis is oriented vertically. 

point-function A function specifying how a point on the ellipse is to 

be drawn on a raster device and possibly specifying any other opera- 
tions to be performed in conjunction with drawing the point. This 
function must take two arguments, x and y, the point's coordinates. 
A point function could be, for example, 

(send xstandard-outputx :draw-line x y (1+ x) (1+ y) :draw nil) 

separate-quadrants A Boolean option specifying whether all the points in a 
quadrant should be drawn before the another quadrant is started. 
When separate-quadrants is t, each quadrant's points are drawn in 
turn, making it possible for the points to be a connected set of line 
segments. This is necessary if the circle is to be part of a path. 
When the default, nil, is taken, the unfilled circle is drawn by call- 
ing draw-circular-ring-driver with appropriate radii. 



(flavorrmethod : draw- wide-curve tv:graphics-mixin) x-array y-array width &op- 
tional end alu Method 

Like :draw-curve, but width is how wide to make the lines. 



graphics:drawing-path (&optional stream &rest draw-path-args) &body body 

Function 
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Draws a fillable figure whose outline is specified by the functions in body, which 
are executed within an implicit progn form. Collects and returns any values pro- 
duced by these functions. The arguments in draw-path-args include any of the key- 
word arguments accepted by the graphics:draw-path function. 

Here is an example in which the progn and value-return features are used, though 
not in drawing a fillable figure: 

(graphics :with-room-for-graphics (t 240) 

(graphics:with-graphics-translation (t 300 100) 
(loop for (angle xa ya) in '((0 :left :center) 



(1/4 


left : baseline) 


(1/2 


center : bottom) 


(3/4 


right :baseline) 


(1 :r- 


ght : center) 


(5/4 


right :top) 


(3/2 


center :top) 


(7/4 


left :top)) 



do 
(multiple-value-bind (x y) 

(graphics:drawing-path (t :filled nil) 
(graphics:set-current-position 0) 
(graphics:draw-l ine-to 100 : rotation (x pi angle)) 
(graphics: cur rent-posit ion)) 
(let ((string (format nil "~(~A+~A~)" xa ya))) 
(graphics:draw-string string x y 

:attachment-x xa :attachment-y ya)))))) 



cent er+bot torn 



right+baseline. 



right +center 



right+top 




lef t+baseline 



lef t+center 



left+top 



center+top 



graphicsrerase-graphics-presentation presentation 
output*) (redisplay-overlapping-presentations t) 



&key (stream 



*standard- 

Function 



Erases a graphics presentation. Graphic presentations 
graphics::with-output-as-graphic-presentation. 



are created with 
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presentation The presentation to erase. 

rstream Specifies the output stream; the default is *standard-output*. 

rredisplay-overlapping-presentations BoolesptkpBcifying 

whether presentations overlapping the erased presentation are re- 
displayed; the default is t. 

For an example: See the function graphics:with-output-as-graphics-presentation. 

For an overview of graphicsrerase-graphics-presentation and related functions: 
See the section "Other Basic Facilities for Graphic Output". 

graphicsrerase-rectangle left top right bottom &key (stream *standard-output*) 

Function 

Clears a rectangular area of a graphics display. 

left The x-coordinate of the left side of the rectangular area. 

top The y-coordinate of the top side of the rectangular area. 

right The x-coordinate of the bottom side of the rectangular area. 

bottom The y-coordinate of the bottom side of the rectangular area. 

rstream Specifies the output stream; the default is *standard-output*. 

For an overview of graphics:with-room-for-graphics and related functions: See 
the section "Other Basic Facilities for Graphic Output". 

rfilled Option 

Boolean option specifying whether all pixels within the figure created by a 
drawing function are turned on, or only the outline pixels; the default is t 
(filled). 

tvrgraphics-mixin Flavor 

A flavor mixed into almost all windows. It provides basic graphics capabilities. 

graphics:graphics-origin-to-current-position &key (stream *standard-output*) 

Function 

Moves the graphics origin (0, 0) to the current position of the graphics cursor. 

rstream Specifies the output stream; the default is *standard-output*. 

This facility is useful with drawing functions that explictly use the graphics cur- 
sor. Such functions include graphics:draw-bezier-curve-to, graphicsrdraw- 
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circular-arc-to, graphics:draw-line-to, and other facilities commonly used for cre- 
ating path-drawing functions. For examples of path-drawing functions: See the 
function graphics:draw-path. 

For an overview of graphics:graphics-origin-to-current-position and related func- 
tions: See the section "Drawing Functions". 

(graphics :with-room-for-graphics (t 100) 
(graphics:with-graphics-translation (t 50 50) 
(graphics :with-graphics-scale (t 50) 
(graphics: drawing-path () 
(graphics:set-current-position 0) 
(dotimes (i 4) 
(graphics:draw-l ine-to 1 0) 

(graphics: graphics-origin-to-cur rent-posit ion) 
(graphics:graphics-rotate (* -4/5 pi))) 
(graph i cs : cl ose-path) ) ) ) ) 



• 



graphicsrgraphics-rotate theta &key (stream *standard-output*) Function 

Modifies the graphics transformation matrix to rotate graphics output; rotation is 
about the local origin. (For an explanation of the graphics tranformation matrix: 
See the function graphicsrwith-graphics-transform.) 

theta A number specifying the rotation in radians. 

rstream Specifies the output stream; the default is *standard-output*. 

Example: 
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(graphics :with-room-for-graphics (t 200) 

(graphics:with-graphics-translation (t 100 100) 
(graphics: draw-point 0) 

(graphics:graphics-rotate (* 1/3 pi)) 

(graphics: draw-rectangle -50 50 50 -50 :filled nil) 

(graphics:graphics-rotate (* -1/3 pi)) 

(graphics:draw-rectangle -50 50 50 -50 :filled nil))) 




This and two related functions (graphicsrgraphics-translate and 
graphics:graphics-scale) are intended primarily for use within path-drawing func- 
tions supplied to graphics:draw-path and graphics:with-clipping-path or within 
graphics encapsulating macros such as graphics:with-room-for-graphics and 
graphicsrwith-graphics-transform. For examples: See the function graphicsrdraw- 
path. In other contexts, graphicsrwith-graphics-rotation is generally more appro- 
priate. 

For an overview of graphicsrgraphics-rotate and related functions: See the section 
"Coordinate System Facilities". Also: See the section "Keyword Options Affecting 
the Coordinate System". 



graphics:graphics-scale x-scale &optional (y-scale graphics: :x-scale) &key (stream 
*standard-output*) Function 

Modifies the graphics transformation matrix to apply a scaling factor to graphics 
output. (For an explanation of the graphics tranformation matrix: See the function 
graphicsrwith-graphics-transform.) 

x-scale A number specifying the x scaling factor. 

y-scale A number specifying the y scaling factor (if different than x-scale). 

rstream Specifies the output stream; the default is *standard-output*. 

Example: 

(graphics:with-room-for-graphics (t 100) 
(graphics:graphics-scale 5 5) 
(graphics:draw-rectangle 10 20 20 10) 
(graphics:graphics-scale 1/2 1/2) 
(graphics:draw-rectangle 10 20 20 10 :gray-level .5)) 
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This and two related functions (graphicsrgraphics-translate and 
graphicsrgraphics-rotate) are intended primarily for use within path-drawing 
functions supplied to graphics:draw-path and graphics:with-clipping-path or 
within graphics encapsulating macros such as graphics:with-room-for-graphics 
and graphicsrwith-graphics-transform. For examples: See the function 
graphics:draw-path. In other contexts, graphics:with-graphics-scale is generally 
more appropriate. 

For an overview of graphics:graphics-scale and related functions: See the section 
"Coordinate System Facilities". Also: See the section "Keyword Options Affecting 
the Coordinate System". 



graphics:graphics-stream-p stream Function 

Returns a Boolean value: t if stream supports the generic graphics protocol; other- 
wise nil. Use this predicate to determine whether to use a graphical or a textual 
representation of an object. 



graphicsrgraphics-transform transform &key (stream *standard-output*) Function 

Modifies the graphics transformation matrix move the origin of the graphics coor- 
dinate system in accordance with the translation, rotation, and scaling specified by 
transform. (For an explanation of the graphics tranformation matrix: See the func- 
tion graphicsrwith-graphics-transform.) 

transform A list of the essential six elements of a two-dimensional homoge- 
neous graphics transformation matrix describing a combination of 
scaling, rotation, and translation. 

rstream Specifies the output stream; the default is *standard-output*. 

Example: 

(graphics :with-room-for-graphics (t 100) 
(graphics: graphics-translate 40 40) 
(graphics: draw-rectangle 40 40 0) 
(graphics: graphics-transform '(2001 10 10)) 
(graphics: draw-rectangle 40 40 :gray-level .5)) 
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This and related functions such as (graphics:graphics-scale and 
graphicsrgraphics-rotate) are intended primarily for use within path-drawing 
functions supplied to graphics:draw-path and graphics:with-clipping-path or 
within graphics encapsulating macros such as graphics:with-room-for-graphics 
and graphicsrwith-graphics-transform. For examples: See the function 
graphics:draw-path. In other contexts, graphicsrwith-graphics-transform is gen- 
erally more appropriate. 

For an overview of graphicsrgraphics-transform and related functions: See the 
section "Coordinate System Facilities". Also: See the section "Keyword Options Af- 
fecting the Coordinate System". 



graphicsrgraphics-translate delta-x delta-y &key (stream *standard-output*) 

Function 

Modifies the graphics transformation matrix to offset the origin of the graphics co- 
ordinate system. (For an explanation of the graphics tranformation matrix: See the 
function graphicsrwith-graphics-transform.) 

delta-x A number specifying the x offset. 
delta-y A number specifying the y offset. 

rstream Specifies the output stream; the default is *standard-output*. 



Example: 



(graphics :with-room-for-graphics (t 100) 
(graphics: graphics-translate 40 40) 
(graphics: draw-rectangle 40 40 0) 
(graphics:graphics-translate -40 -40) 
(graphics: draw-rectangle 40 40 :gray-level .5)) 




This and two related functions (graphics:graphics-scale and graphicsrgraphics- 
rotate) are intended primarily for use within path-drawing functions supplied to 
graphics:draw-path and graphics:with-clipping-path or within graphics encapsu- 
lating macros such as graphics:with-room-for-graphics and graphicsrwith- 
graphics-transform. For examples: See the function graphics:draw-path. In other 
contexts, graphicsrwith-graphics-translation is generally more appropriate. 
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For an overview of graphicsrgraphics-translate and related functions: See the sec- 
tion "Coordinate System Facilities". Also: See the section "Keyword Options Affect- 
ing the Coordinate System". 



:gray-level Option 

Specifies the black-to-white level of the graphic as a ratio or decimal fraction 
between and 1; the default value is 1. On 1-bit devices, gray levels are sim- 
ulated by stippling. 

Example: 

(defun gray-level -example () 

(graphics :with-room-for-graphics (t 200) 
(graph i cs : draw-pol ygon 

'(100 10 350 10 350 100 225 150 100 100 100 10) 
: gray-level 1/4 
:convex-p t) 
(graphics: draw-pol ygon 

'(100 10 350 10 350 100 225 150 100 100 100 10) 
:filled nil 
:convex-p t) 
(graphics: draw-pol ygon 

'(259 137 259 165 289 165 289 124 259 137) 
: gray-level 3/4 
:convex-p t) 
(graphics:draw-rectangle 200 70 250 10 

: gray-level 1/2 
: opaque t) 
(graphics:draw-rectangle 200 70 250 10 

:filled nil) 
(graphics:draw-rectangle 135 90 175 40 

: gray-level 1/20 
: opaque t) 
(graphics:draw-rectangle 135 90 175 40 

:filled nil) 
(graphics:draw-l ine 135 65 175 65) 
(graphics:draw-rectangle 275 90 315 40 

: gray-level 1/20 
: opaque t) 
(graphics:draw-rectangle 275 90 315 40 

:filled nil) 
(graphics:draw-l ine 275 65 315 65))) 
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(gray-1 evel -exampl e) 




graphics:gray-level-stipple gray-level Function 

Returns a stipple array that approximates gray-level, a number between and 1. 

Example: 

(graphics :with-room-for-graphics (t 100) 
(graphics :draw-ci rcle 50 50 50 :stipple (graphics: gray-level -stipple .5))) 



graphics:*identity-transform* 



Variable 



The list (10 10 0), which is the representation of the two-dimensional homoge- 
neous transform matrix: 

10 
10 
1 

Applying the identity transform to any set of coordinates results in the same set of 
coordinates. Composing the identity transform with any other transform t results 
in t. See the section "Coordinate System Facilities". 



:initial-dash-phase 



Option 



Specifies the offset, in pixels, of the start of the first dash from the starting 
point of the line; the default value is 0. 

This option is not operable if the rdashed option to the drawing function is 
nil. 



graphicsrinvert-transform transform &optional (into-transform (graphicsrmake- 
graphics-transform)J Function 



transform 



A list of the essential six elements of a two-dimensional homoge- 
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neous graphics transformation matrix describing a combination of 
scaling, rotation, and translation. 

into-transform Another such list that is to become the result of the 

inversion. 

Returns or optionally stores into into-transform the result of calculating the in- 
verse of the matrix represented by transform. Application of the transform result- 
ing from graphicsrinvert-transform to a point originally moved by applying trans- 
form will restore the point to its original location. See the section "Coordinate Sys- 
tem Facilities". 



:line-end-shape Option 

Specifies the shape for the ends of lines drawn by a drawing function, one of 
:butt, rsquare, rround, or :no-end-point; the default is :butt. 

To see the differences among end shapes, try evaluating the following: 

(graphics :with-room-for-graphics (t 200) 
(graphics: draw-line 200 40 200 140 

: 1 ine-end-shape :butt 

:thickness 20) 
(graphics:draw-line 240 40 240 140 

: 1 ine-end-shape :no-end-point 

:thickness 20) 
(graphics:draw-line 280 40 280 140 

: 1 ine-end-shape : square 

:thickness 20) 
(graphics:draw-line 320 40 320 140 

: 1 ine-end-shape : round 

:thickness 20) 
(graphics:draw-line 190 30 330 30) 
(graphics:draw-line 190 150 330 150)) 

The vertical lines on the left have rbutted ends; they do not extend beyond 
the y-coordinates (40 and 140) given for the line. The lines on the right have 
rsquared and rrounded ends. These lines extend, because of the rthickness 
parameter (20), 10 pixels above and below the top and bottom line coordinates. 

This option is not operable if the function draws a filled (: filled t) figure. 



graphicsrline-intersection xl yl x2 y2 x3 y3 x4 y4 &optional (interval rclosedj 

Function 

Returns the intersection point of the two lines specified by <xl yl> to <x2 y2> and 
<x3 y3> to <x4 y4>, or nil if the lines do not intersect, interval can be t to indicate 
you want the intersection point wherever it is, :open to indicate the endpoints do 
not count as matching, or rclosed (default) to include endpoints. 
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(defun show-line-intersection (x1 y1 x2 y2 x3 y3 x4 y4) 
(graphics: with- room-for-graphics () 
(graphics :draw-l ine x1 y1 x2 y2) 
(graphics:draw-l ine x3 y3 x4 y4) 
(block done 
(multiple-value-bind (x y) 

(graphics: 1 ine-intersection x1 y1 x2 y2 x3 y3 x4 y4) 
(when (and x y) 
(return-f rom done 
(graphics:draw-arrow x y)))) 
(multiple-value-bind (x y) 

(graphics: 1 ine-intersection x1 y1 x2 y2 x3 y3 x4 y4 t) 
(when (and x y) 
(return-from done 
(graphics:draw-arrow x y :dashed t))))))) 

(show-line-intersection 100 200 100 100 100 200 0) 




(show-line-intersection 100 50 150 50 100 200 150 175) 



:line-joint-shape 



Option 



Specifies the shape of joints between line segments of closed, unfilled figures, 
when the rthickness option to a drawing function is greater than 1. The pos- 
sible shapes are rmiter, rbevel, rround, and :none; the default is rmiter. 

The following example draws four pentagons illustrating the differences 
among, from left to right, the rmiter, rbevel, rround, and mone joint shapes: 
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(graphics :with-room-for-graphics (t 200) 

(graphics: draw-regular-polygon 40 40 100 40 5 

:filled nil 
:thickness 15 
: 1 ine-joint-shape :miter) 

(graphics:draw-regular-polygon 190 40 250 40 5 

:filled nil 
:thickness 15 
: 1 ine-joint-shape :bevel) 

(graphics:draw-regular-polygon 340 40 400 40 5 

:filled nil 
:thickness 15 
: 1 ine-joint-shape : round) 

(graphics:draw-regular-polygon 490 40 550 40 5 

:filled nil 
thickness 15 
line-joint-shape :none)) 



oooo 



This option is not operable if the function draws a filled (: filled t) figure. 

Some hardcopy devices may not support all line joint shapes. Notably, 
PostScript printers treat :none as rbevel. 



graphicsrmake-contrasting-pattern index-number number-of-indices 



Function 



Returns a pattern instance that draws a distinct (recognizably different) pattern 
for adjacent indices. This is done with a few colors if the output stream supports 
color and with a few stipples otherwise. 

Example: 
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(defun pie-chart () 
(let ((ni terns 4) 

(total 2.0)) 
(graphics :with-room-for-graphics (t 300) 

(graphics:with-graphics-translation (t 350 150) 
(loop for (fraction . rest) on '(1.0 .7 .1 .2) 
for angle = (* pi 1/2) then nangle 
as nangle = (if rest (- angle 

(* graphics:2pi (/ fraction total))) (* pi 5/2)) 
for item-no from 
do 
(graphics:draw-ci rcle 50 :start-angle angle 
:end-angle nangle :clockwise t 
: pattern 

(graphics :make-contrasting-pattern item-no ni terns)) 



(graphics:draw-ci rcle 50 



(graphics:draw-l ine 50 



start-angle angle 
end-angle nangle 
clockwise t 

filled nil :thickness 2) 
rotation angle 
thickness 2)))))) 



graphicsrmake-device-conditional-pattern device-alist 



Function 



Creates a pattern instance that draws in a way that is conditionalized by the out- 
put stream. Each device-alist element is (type . drawing-args). The types are: 



rcolor 
rpostscript 
rwindow 
otherwise 



A stream that can draw in color. 

A stream that goes to a postscript interpreter. 

A window stream. 

(the symbol otherwise) Anything. 



The first element that matches is used, which means that drawing is done with its 
drawing-args, which is a set of keyword/value pairs acceptable to graphicsrwith- 
drawing-state. Example: 

(graphics:with-room-for-graphics (t 100) 
(graphics:draw-rectangle 75 90 :pattern 

(graph i cs : make-devi ce-condi ti onal -pattern 
l ((:color :color :magenta) 

(otherwise :stipple ,stipples:horizontal-dashes))))) 



graphicsrmake-graphics-transform &key :rll :rl2 :r21 :r22 :tx :ty 



Function 
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The defstruct constructor for a transform matrix: it returns the transform matrix 
specified by the keyword arguments. See the section "Advanced Transformation Fa- 
cilities". 



graphicsrmake-identity-transform Function 

Creates and returns the list (10 10 0). 



graphics:make-raster-array-with-correct-width width height &rest args &key (el- 
ement-type t) &allow-other-keys Function 

width The minimum width of the raster array in pixels. 

height The height of the raster array. 

args A list containing the remaining arguments, which can include the 

keyword argument :element-type and other keys, which are the pos- 
sible options for make-array. 

:element-type Specifies the element type of the raster array. One of 

(unsigned-byte n), fixnum, character, string-char, or boolean. 

See the section "Common Lisp Array Element Types". 

Calls make-raster-array with the width argument adjusted if necessary to ensure 
that it is an acceptable width for a raster array (that is, it is a multiple of 32 so 
it can be used by bitblt). 



graphicsrmake-simple-pattern &rest drawing-args Function 

Returns a pattern instance which does the drawing as if drawing-args had been 
passed in place of :pattern <instance>. The possible drawing arguments are the 
same as those acceptable to graphics:with-drawing-state. The most useful key- 
words to include are :alu, rpattern, rstipple, :tile, :gray-level, rcolor, and ropaque. 

(graphics :with-room-for-graphics (t 100) 

(graphics :draw-ci rcle 50 50 50 :pattern 
(graph i cs : make-si mpl e-pattern 

: stipple stipples:weave8 : gray-level .5)) 



graphics:make-two-color-stipple stipple ones-color zeros-color Function 

Returns a pattern instance that draws the stipple pattern stipple in the two colors 
specified by ones-color and zeros-color. If the output stream does not support color, 
the stipple is drawn in black-and-white in the normal way. 

Example: 
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(graphics :with-room-for-graphics (t 100) 
(graphics :draw-ci rcle 50 50 50 :pattern 

(graph i cs : make- two-col or-sti ppl e 
stipples: fil led-diamonds 
: red : yellow))) 



graphicsrmap-points function points Function 

function A function that accepts three arguments: x, y, and last-point-p. This 
last argument is a Boolean which indicates that this is the last 
point to be processed. 

points A sequence, that is, a list or an array, of x and y coordinates of a 
collection of points, for example, (xl yl x2 y2 x3 y3 x4 y4). 

Sequentially calls function on each coordinate pair in the sequence. 



:mask Option 

Specifies a bitmap of points affected by the drawing operation; the default is 
nil, that is, no bitmap. 

Use this option to mask out portions of the output graphic that you do not 
want displayed. For example, the following form outputs a rectangle, but does 
so through a triangular mask, so that only a triangle gets displayed: 

(graphics:with-room-for-graphics (t 200) 
(multiple-value-bind (bitmap x y) 

(graphics :with-output-to-bitmap () 

(graphics:draw-triangle 100 50 200 150 300 50)) 
(graphics:draw-rectangle 200 400 

: gray-level .33 

:mask bitmap :mask-x x :mask-y (+ 100 y)))) 



:mask-x Option 

Specifies the x-coordinate, with respect to the local graphics origin, of the 
lower lefthand corner of the position of the rectangular bitmap region speci- 
fied by the :mask option. 



:mask-y 
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Option 



Specifies the y-coordinate, with respect to the local graphics origin, of the 
lower lefthand corner of the position of the rectangular bitmap region speci- 
fied by the :mask option. 



ropaque 



Option 



Boolean option specifying whether pixels in the source pattern of a drawing 
function are cleared (before the graphic is output) or left alone; the default is 
t. ropaque t means draw pixels that are off in the background color. The re- 
sult of ropaque t is not influenced by the ralu supplied for the pixels that are 
on. If you draw something over an existing figure using ropaque t ralu :flip, 
the pixels that were originally on are inverted, and pixels that were originally 
off are cleared (set to the background color). 

To see the effect of this option, try calling the following function with t and 
then nil. 

(defun opaque-example (t-or-nil) 

(graphics :with-room-for-graphics (t 200) 
(graphics :draw-ci rcle 200 100 50 

: pattern tv: 75%-gray) 
(graphics:draw-triangle 165 65 235 65 200 150 

: pattern tv:25%-gray 
: opaque t-or-nil))) 

(opaque-example t) 




(opaque-example nil) 
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rpattern Option 

Specifies a pattern to be drawn within the figure created by a drawing func- 
tion, rpattern is the most general control of the "looks" of thie inside of a 
filled shape. The default is nil. The rpattern drawing option can be a(n) 

• stipple This is identical to rstipple <value>. 

• color This is identical to rcolor <value>. 

• instance The case of interest here. 

Several functions are provided for making instances to pass as the pattern. 
See the function graphicsrmake-simple-pattern. See the function 
graphicsrmake-two-color-stipple. See the function graphicsrmake- 
contrasting-pattern. See the function graphicsrmake-device-conditional- 

pattern. Additionally, there are three layered protocols for implementing 
one's own instances to be passed as rpattern. See the section "Texturing". 

(defun pattern-examplel () 

(graphics :with-room-for-graphics (t 200) 
(let ((bitmap (tv: make-binary-gray 8 8 



The picture of 
what you want 
the bit pattern 
displayed to 
look like, in 
this case the 
number 1 . 



'(#b00000000 
#b00001000 
#b00111000 
#b00001000 
#b00001000 
#b00001000 
#b00001000 
#b00111110)))) 
(graphics:draw-ci rcle 200 100 50 

: pattern bitmap)))) 

(defun pattern-example2 () 

(let ((bitmap (tv:with-output-to-bitmap (t) 
(graphics: draw-string 
"symbolics" 
: character-style 

'(:swiss :bold-italic :large))))) 
(graphics:with-room-for-graphics (t 250) 

(graphics:draw-triangle 100 25 400 25 250 250 

: pattern bitmap)))) 
(pattern-exampl e1 ) 
(pattern-exampl e2) 



graphicsrpattern-call-with-drawing-parameters pattern function stream drawing- 
state Generic Function 
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As implemented by pattern, which should be built upon graphicsrbasic-pattern, 
should call function with keyword arguments such as would be acceptable to 
graphics:with-drawing-state. It can examine stream and drawing-state to deter- 
mine what arguments to supply. See the section "Texturing". Example: 

(defflavor my-pattern () (graphics: basic-pattern)) 

(def method (graphics : patter n-cal 1-with-drawing-parameters 
my-pattern) 
(function stream drawing-state) 
(ignore drawing-state) 
(if (color :color-stream-p stream) 

(funcall function :color :magenta) 

(funcall function :stipple stipples: hearts :gray-level .75))) 

(compi 1 e-f 1 avor-methods my-pattern) 

(graphics: with- room-for-graphics () 

(graphics:draw-rectangle 200 100 :pattern (make-instance 

'my-pattern))) 

Note that this example could have been done in a data-driven way rather than in 
this procedural way by using graphicsrmake-device-conditional-pattern. 



graphicsrpattern-compute-raster-source-pattern pattern source-so-far ones-alu ze- 
ros-alu temporary-p stream drawing-state Generic Function 

Returns updated-source, ones-alu, zeros-alu, and temporary-p; fills in the source-so- 
far with pattern; and updates the alus with ones-alu and zeros-alu. If temporary-p is 
true, the temporary raster sheet is deallocated. Pattern is to be drawn on stream 
with drawing-state. Methods that need to exercise fuller control over the individual 
slices in the shape should return self as the source. See the section "Texturing". 
Example: 

(defflavor my-pattern-2 () (graphics: raster-device-pattern)) 
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(def method (graphi cs : pattern-compute-raster-source-pattern my-pattern-2) 
(source-so-far ones-alu zeros-alu temporary-p ignore ignore) 
;; Get a raster we can modify, 
(unless temporary-p 

(multiple-value-bind (width height) 
(if source-so-far 

(multiple-value-bind (width height) 

(decode- raster-array source-so-far) 
(values (1cm width 32) height)) 
(values 32 1)) 
(let ((source (with-stack-1 ist (dims height width) 

(tv : al 1 ocate-temp-sheet-raster-and-header 

dims :type 'tv:art-1b)))) 
(if source-so-far 

(bitblt boole-1 width height source-so-far source 0) 
(bitblt boole-set width height source source 0)) 
(setq source-so-far source 
temporary-p t)))) 
(multiple-value-bind (width height) 

(decode- raster-array source-so-far) 
(bitblt boole-xor width height stipples: vertical-1 ines 

source-so-far 0)) 
(values source-so-far ones-alu zeros-alu temporary-p)) 

(compi 1 e-f 1 avor-methods my-pattern-2) 

(graphics: with- room-for-graphics () 

(let ((pattern (make-instance 'my-pattern-2))) 

(graphics:draw-rectangle 200 100 :pattern pattern) 
(graphics:draw-rectangle 100 200 200 

: stipple stipples: hearts : pattern pattern))) 



graphics:pattern-draw-raster-slice pattern width height x y ones-alu zeros-alu 
stream drawing-state Generic Function 

pattern should use some of the primitive raster drawing messages (such as :draw- 
rectangle or :draw-l-bit-raster) to output an appropriately patterned slice to 
stream whose upper-left corner is at x,y and whose size is width,height. See the 
section "Texturing". Example: 

(def flavor random-pattern 
(phase) 
(graphics: raster-sl ice-device-pattern 

1 gp : postscri pt-devi ce-pattern) 
(constructor make-random-pattern (phase))) 
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(def method (graphics :pattern-draw-raster-sl ice random-pattern) 

(width height x y ones-alu zeros-alu stream ignore) 

(let ((raster (graphics:make-raster-array-with-correct-width 

width height 
: element-type 'bit))) 
(loop for real-y from y 

for y from below height 
do 
(loop repeat (floor (* width (mod real-y phase)) phase) 
do 
(setf (raster-aref raster (random width) y) 1))) 
(send stream :draw-1-bit-raster width height 

raster x y ones-alu zeros-alu))) 

(def method (lgp: pattern-output-postscript-code random-pattern) 
(device-stream filled ignore ignore) 
(format device-stream 

"8 (pop pop 1 rand and} setscreen .25 setgray ") 
(write-string (if filled "fill" "stroke") device-stream)) 

(compi 1 e-f 1 avor-methods random-pattern) 

(graphics:with-room-for-graphics (t 100) 
(graphics:draw-triangle 50 100 100 

: pattern (make-random-pattern 8))) 



lgp:pattern-output-postscript-code pattern device-stream filled stream drawing-state 

Generic Function 

As implemented by pattern, which should be built upon lgprpostscript-device- 
pattern, should send PostScript code to device-stream, which will be a thin charac- 
ter output stream. The current path will be the figure being drawn, filled is t if 
the outline is to be filled and nil if it is to be stroked. The implementation can ex- 
amine stream and drawing-state to determine what to do. See the section "Textur- 
ing". 



graphics:*pattern-stipple-arrays* Variable 

A list of those stipple arrays that are patterns, as opposed to gray levels. 
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See the variable graphics:*stipple-arrays*. 
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(flavorrmethod rpoint tv:graphics-mixin) x y 



Method 



Returns the numerical value of the picture element at the specified coordinates. 
The result is or 1 on a black-and-white TV. Clipping is performed; if the coordi- 
nates are outside the window, the result will be 0. 



lgprpostscript-device-pattern 



Flavor 



The flavor for patterns on postscript devices. Built on graphicsrraster-device- 
pattern, it has the required method, lgp:pattern-output-postscript-code. 



graphics:raster-graphics-mixin 



Flavor 



A flavor mixin to windows and other raster devices that implements graphics by 
means of primitive slice functions. 



graphics:read-encoded-graphics-as-characters stream 



Function 



Returns an array with elements of type (unsigned-byte 8), which contains an en- 
coded version of a graphics function. 

See the function graphics:binary-encode-graphics-to-array.See the section "Other 
Advanced Facilities for Graphic Output". 
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stream A character stream to which an encoded graphics function has been 
written with the function graphics:write-encoded-graphics-as- 
characters. 



graphicsrreplacing-graphics-presentation (stream presentation &rest args) &body 
body Function 

Replaces a graphic presentation with the graphic output generated in body. The 
new output will also be a graphics presentation and is returned as such. The re- 
placing operation is done in such a way that flicker is minimized, making this fa- 
cility useful for simple animations. Returns two values, the old display, which is a 
bitmap stream, and the pattern array generated by the body. 

stream The output stream. 

presentation The graphics presentation to be replaced. 

args Optional keyword arguments, including :pattern-array, the array 

that holds the pattern array generated by the body, and rbitmap- 
stream, a specially allocated raster array that contains the old dis- 
play. 

The following example illustrates the use of the rbitmap-stream and rpattern- 
array options to graphicsrreplacing-graphics-presentation: 

(defun animation-example () 

(graphics :with-room-for-graphics (t 150) 

(graphi cs : wi th-output-to-bi tmap-stream (bi tmap-stream 

:for-stream xstandard-outputx) 
(let ((old-output nil) 

(old-pattern nil)) 
(loop for i to 25 

as x = (+ 100 (* i 16)) 
do 
(mul tiple-value-setq (old-output old-pattern) 

(graphics: replacing-graphics-presentation (t old-output 
: pattern-array old-pattern 
: bitmap-stream bitmap-stream) 
(graphics:with-graphics-translation (t x 100) 
(graphics:draw-ci rcle 20) 
(let ((angle (/ (* pi i) 25))) 

(graphics:draw-triangle 20 40 40 10 

: rotation angle) 
(graphics:draw-ci rcle 30 

: inner-radius 20 :start-angle angle)))))))))) 

(animation-example) 

Use of the options as illustrated saves the cost of allocation of arrays and bitmap 
streams each time around the loop. For an overview of graphicsrreplacing- 
graphics-presentation and related functions: 
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See the section "Other Basic Facilities for Graphic Output". 



rreturn-presentation Option 

Boolean option specifying whether a drawing function should return the newly 
created graphic as a presentation object; the default is nil. 

Use this option when you wish to manipulate the output of a single drawing 
function as a presentation. If you want to manipulate the collective output of 
a series of drawing functions as a single presentation, use the graphicsrwith- 
output-as-graphics-presentation macro instead. 

Some facilities are provided for handling graphic presentations, in particular, 
graphicsrerase-graphics-presentation and graphicsrreplacing-graphics- 
presentation. The following example uses the former in conjunction with the 
rreturn-presentation keyword: 

(graphics :with-room-for-graphics (t 100) 
(graphics :with-graphics-scale (t 50) 
(let ((presentations 
(list 
(graphics: draw-regular-polygon .75 .5 1.25 .5 4 
: gray-level .25 : return-presentation t) 
(graphics: draw-regular-polygon .25 1.25 3 

: gray-level .75 : return-presentation t) 
(graphics:draw-el 1 ipse 1.5 .5 .4 .4 

: gray-level .5 : return-presentation t)))) 
(sleep 2) 
(graphics:erase-graphics-presentation (first presentations))))) 



rrotation Option 

Specifies the rotation of the graphic in plus or minus radians; the default is 
0. The axis of rotation is the local origin (0, 0). 

In the following example, the origin is first established at the lower, left 
corner of the graphic display area created by graphics:with-room-for- 
graphics, then translated 300 pixels to the right and 15 pixels up by the 
graphicsrwith-graphics-translation macro. In this coordinate system, the ar- 
row is rotated counter-clockwise about the origin at an offset of 10 pixels. 
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(defun rotating-arrow () 

(graphics :with-room-for-graphics (t 225) 

(graphics:with-graphics-translation (t 300 15) 

(graphics: draw-arrow 10 200 

:thickness 5) 

(sleep .2) 

(graphics:draw-arrow 10 200 

:thickness 5 

: rotation (* pi . 125)) 

(sleep .2) 

(graphics:draw-arrow 10 200 

:thickness 5 

: rotation (* pi .25)) 

(sleep .2) 

(graphics:draw-arrow 10 200 

:thickness 5 

: rotation (* pi .375)) 

(sleep .2) 

(graphics:draw-arrow 10 200 

:thickness 5 

: rotation (* pi .5)) 

(sleep .2) 

(graphics:draw-arrow 10 200 

:thickness 5 

: rotation (* pi .625)) 

(sleep .2) 

(graphics:draw-arrow 10 200 

:thickness 5 

: rotation (* pi . 75)) 

(sleep .2) 

(graphics:draw-arrow 10 200 

:thickness 5 

: rotation (* pi .875)) 

(sleep .2) 

(graphics:draw-arrow 10 200 

:thickness 5 

: rotation pi)))) 

(rotating-arrow) 



graphicsrsaving-graphics-transform f&optional stream) &body body Function 

Perform body while stream has a modifiable copy of its current transformation 
matrix. That is, functions like graphicsrgraphics-rotate can be called from within 
graphicsrsaving-graphics-transform without permanent effect. 
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rscale Option 

Specifies a number applied as a scaling factor to the x and y parameters of a 
drawing function; the default is 1. 

rscale does not affect the line thickness parameter. To do so, use the rscale- 
thickness keyword. 

(graphics :with-room-for-graphics (t 100) 
(graphics :draw-ci rcle 1 1 1 :scale 20)) 




rscale-dashes Option 

Boolean option specifying whether to scale dashes when the rdashed option to 
a drawing function is t and a scaling factor is specified (via the rscale key- 
word: See the option rscale.). The default is nil. 

For an example: See the option rdash-pattern. 

This option is not operable if the rdashed option is nil. 



scale-float float integer Function 

Computes and returns (* float 2 inte 9 er ). 

Although the same result can be obtained by using exponentiation and multiplica- 
tion, the use of scale-float can be much more efficient and avoids the intermediate 
overflow and underflow if the final result is representable. 

Examples: 

(scale-float .5 2) => 2.0 

(scale-float .5 3) => 4.0 

(scale-float .5 4) => 8.0 

(scale-float .75 2) => 3.0 

For a table of related items, see the section "Functions that Decompose and Con- 
struct Floating-point Numbers". 

r scale-thickness Option 

Boolean option specifying whether to scale thickness, as well as other linear 
dimensions, when a scaling factor is specified (via the rscale keyword to a 
drawing function: See the option rscale.). The default is nil. 

This option is not operable if the function draws a filled (: filled t) figure. 



(graphics :with-room-for-graphics (t 100) 
(graphics:with-graphics-translation (t 100 50) 
(graph i cs : draw-rectangl e 
(graph i cs : draw- rectangl e 
(graphics: draw-rectangl e 
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thickness 1) 
thickness 1 :scale 2) 
thickness 1 :scale 4 



:scale-thickness nil))) 





□ 





graphics:sector-wide-p start-angle end-angle 



Function 



Returns a Boolean value that is t if the angle from start-angle to end-angle is no 
more than a quarter circle in the clockwise direction; otherwise nil. 

(graphics:sector-wide-p (* pi 1/4) (* pi 3/8)) 
NIL 



graphicsrset-current-position new-x new-y &key {stream *standard-output*) {ex- 
plicit t) Function 

Moves the graphics cursor to a specified position. 

new-x The new x-coordinate. 
new-y The new y-coordinate. 

rstream Specifies the output stream; the default is *standard-output*. 

rexplicit Boolean optionspecifyingwhetherthismovementopensupanew 

portion of a path for graphics:draw-path; the default is t. Specify 
nil for operations that do output and then move the cursor. 

This facility is useful with drawing functions that explictly use the graphics cur- 
sor. Such functions include graphics:draw-bezier-curve-to, graphicsrdraw- 
circular-arc-to, graphics:draw-line-to, and other facilities commonly used for cre- 
ating path-drawing functions. For examples of path-drawing functions: See the 
function graphics:draw-path. 

For an overview of graphicsrset-current-position and related functions: See the 
section "Drawing Functions". 



graphicsrstandard-graphics-mixin 



Flavor 
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A flavor mixin defining required methods of graphics primitives. It should be in- 
cluded in all streams that support graphics. 



graphics:*stipple-arrays* 



Variable 



A list of predefined stipple arrays that can be specified for the graphics rstipple 
option. These are the names of the arrays in the list: 



stipples:large-diamonds 

stipples:filled-diamonds 

stipples:weave8 

stipple s : diagonals 

stipples:hearts 

stipples:double-bricks 

stipples:bricks 

stipples:horizontal-lines 

stipples:horizontal-dashes 

stipples: alt-rain 

stipples: southeast-rain 

stipples: southeast-thick-hatch 

stipples: southeast-thin-hatch 

stipples: southeast-dense-hatch 

stipples:6%-gray 

stipples:8%-gray 

stipples:10%-gray 

stipple s : he s-gr ay 

stipples: 75%-gray 

stipples:50%-gray 



stipples: small-diamonds 

stipples:weave8b 

stipples:parquet 

stipples: small-diamonds 

stipples: tiles 

stipple s : half -bricks 

stipple s : vertical-line s 

stipples:vertical-dashes 

stipples: tracks 

stipple s : south we st-r ain 

stipple s : south we st-thick-hatch 

stipple s : south we st-thin-hatch 

stipples: southwest-dense-hatch 

stipples:5.5%-gray 

stipples: 7%-gray 

stipples:9%-gray 

stipples:12%-gray 

stipples:33%-gray 

stipples:25%-gray 



: stream 



Option 



Specifies the output stream for a drawing function; the default is *standard- 
output*. 



graphicsrstream-transform stream 



Function 



stream Any graphics stream, that is, any stream that has a flavor compo- 
nent of graphics:standard-graphics-mixin. 

Returns a list whose elements are the current transform matrix of stream. If the 
coordinate context is established with one of the graphicsrwith-graphics ... 
macros, the value returned is a stack list. See the section "Coordinate System Fa- 
cilities". 



graphics:stream-transform-point x y stream 



Function 
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Returns the result of transforming the point <x y> by the inverse of the current 
transformation matrix of stream, that is, it returns the coordinates the point would 
have if the current transformation matrix were not applied. 



graphics:stream-untransform-point x y stream Function 

Returns the result of transforming the point <x y> by the current transformation 
matrix of stream. 



:scale-x Option 

Specifies a number applied as a scaling factor to the x parameters of a draw- 
ing function; the default is 1. 

(graphics :with-room-for-graphics (t 100) 



(graphics :draw-ci rcle 50 50 20 :scale-x 4)) 



:scale-y Option 

Specifies a number applied as a scaling factor to the y parameters of a draw- 
ing function; the default is 1. 

(graphics :with-room-for-graphics (t 100) 
(graphics:draw-circle 100 100 50 :scale-y 1/2)) 



rthickness Option 

Specifies the thickness, in pixels, of the line or lines drawn by a drawing 
function. The default is device-dependent: for the screen, it is 0, which speci- 
fies the minimum thickness for that device; for the lgp2 and lgp3, it is 1. The 
thinnest possible thickness is 0, which also specifies that the line is to be po- 
sitioned roughly. For accurate positioning, specify a thickness of 1. 

This option is not operable if the function draws a filled (: filled t) figure. 

(graphics :with-room-for-graphics (t 100) 

(graphics: draw-triangle 50 25 25 :filled nil :thickness 2) 

(graphics: draw-triangle 100 150 125 25 :filled nil :thickness 4) 

(graphics:draw-triangle 200 250 225 25 :filled nil :thickness 8)) 



Z\ ^ 




rtransform Option 
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Specifies a list of six elements in the graphics transformation matrix applied 
to the local coordinate system used for a drawing function. The element order 
is a, b, c, d, x, and y (see below). The default is nil, resulting in no transfor- 
mation. 

Arbitrary transformation of coordinates is effected by multiplication of coordi- 
nate vectors by a transformation matrix. For coordinates in two-dimensional 
space, a 3 x 3 transformation matrix is used, 



x y 1 

of which the elements in the third column are constant. Thus, six elements, 
effectively control the transformation as follows: 

• Scaling in the x and y dimensions is controlled by elements a and d, re- 
spectively. Values of 1 for these elements result in no scaling. 

• Translation in the x and y dimensions is controlled by elements x and y, 
respectively. Values of for these elements result in no translation. 

• Rotation about the origin is controlled by elements a, b, c, and d. Counter- 
clockwise rotation by an angle a is effected by a = cosa, b = since, c = - 
sina, and d = cosa. A value of for b and c results in no rotation (a = 0). 

Example: 

This example scales the size of the rectangle by a 
factor of 4 and translates its position by 100 in 
the x direction and 50 in the y direction. 

(graphics:with-room-for-graphics (t 200) 
(graphics:draw-rectangle 20 20 

:transform '(4 4 100 50))) 



graphicsrtransform-distance x y transform Function 

Returns the product of the matrix multiplication of the vector <x, y> and the 
transformation matrix of transform. The values returned are the transformed val- 
ues of the x and y distances. See the section "Coordinate System Facilities". 

x A number representing a distance along the x direction. 

y A number representing a distance along the y direction. 

transform A list of the essential six elements of a two-dimensional homoge- 
neous graphics transformation matrix describing a combination of 
scaling, rotation, and translation. 
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graphics:transform-point x y transform Function 

Returns the product of the matrix multiplication of the vector <x, y> and the 
transformation matrix of transform. The values returned are the transformed coor- 
dinates of the point. See the section "Coordinate System Facilities". 

x A number representing the x-coordinate of a point. 

y A number representing the y-coordinate of a point. 

transform A list of the essential six elements of a two-dimensional homoge- 
neous graphics transformation matrix describing a combination of 
scaling, rotation, and translation. 



rtranslation Option 

Specifies x and y offsets relative to the local origin (0, 0) used for a drawing 
function. The offsets are specified as a list, (x y) . The offset units depend on 
the output device; if it is the terminal screen, the units are pixels. 

Using this option has the effect of moving the local origin to the new position 
specified by x and y. The default is nil, no translation. 

;;; Contrast this with giving 50 50 as the center, which would have caused it to 
; ; ; be rotated. 

(graphics:with-room-for-graphics (t 100) 
(graphics:draw-el 1 ipse 40 20 :translation '(50 50) :rotation (/ pi 4))) 



s 



graphicsruntransform-distance x y transform Function 

Returns the product of the matrix multiplication of the vector <x, y> and the in- 
verse of the transformation matrix represented by transform. The values returned 
are the original values of x and y; that is, if the given distance <x, y> is the re- 
sult of having undergone transform transform, then graphicsruntransform- 
distance returns the coordinates of the original distance. 

Another way to look at the result is to consider that transform is composed of a 
set of transformations of a point: a translation, followed by a rotation, followed by 
a scaling, graphicsruntransform-distance performs these same transformations in 
reverse, restoring the transformed distance to its original values. See the section 
"Coordinate System Facilities". 

x A number representing a distance along the x direction. 

y A number representing a distance along the y direction. 
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transform A list of the essential six elements of a two-dimensional homoge- 
neous graphics transformation matrix describing a combination of 
scaling, rotation, and translation. 



graphics:untransform-point x y transform Function 

Returns the product of the matrix multiplication of the vector <x, y> and the in- 
verse of the transformation matrix represented by transform. The values returned 
are the original coordinates of the point <x, y>; that is, if the given point <x, y> 
is at its current location as a result of having undergone transform transform from 
some original location, then graphics:untransform-point returns the coordinates 
of that original location. 

Another way to look at the result is to consider that transform is composed of a 
set of transformations of a point: a translation, followed by a rotation, followed by 
a scaling. graphics:untransform-point performs these same transformations in re- 
verse, restoring the transformed point to its original coordinates. See the section 
"Coordinate System Facilities". 

x A number representing the x-coordinate of a point. 

y A number representing the y-coordinate of a point. 

transform A list of the essential six elements of a two-dimensional homoge- 
neous graphics transformation matrix describing a combination of 
scaling, rotation, and translation. 

graphicsruntransform-window-points stream &rest points Macro 

points A list of numbers representing pairs of x- and y-coordinates of 
points. 

Modifies a list containing the products of the matrix multiplication of each vector 
<x, y> and the inverse of the transformation matrix of stream. The new values in 
the list are the transformed coordinates of the points. 

See the macro graphicsrtransform-window-points.See the section "Coordinate Sys- 
tem Facilities". 



graphics:with-clipping-from-output (stream &body clipping-region-body) &body out- 
put-body Function 

Binds the local environment to apply a clipping region to the output of drawing 
functions in the body. The clipping region limits output from the drawing func- 
tions to points within the region. The shape of the clipping region is defined by a 
drawing function. 

stream The output stream. 
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clipping-region-body A drawing function outlining the clipping region. This 
can be any function generating a closed figure as output, including 
functions based on graphics:draw-path for complex figures. Output 
should be to stream. 

graphics:with-clipping-path is a facility closely related to graphicsrwith-clipping- 

from-output. You use it to apply clipping regions defined by path-drawing func- 
tions, rather than by drawing functions as in the case of graphicsrwith-clipping- 
from-output. For an example illustrating the use of the two facilities: See the 
function graphics:with-clipping-path. 

For an overview of graphics:with-clipping-from-output and related functions: See 
the section "Drawing Functions". 



graphics:with-clipping-mask (stream mask &rest mask-args) &body body Macro 

Performs the graphics output specified by body on stream using mask as a clipping 
region. This is similar to using a drawing function with :mask mask, mask-args 
are &key (left 0) (top 0) right bottom. 



graphics:with-clipping-path (stream path-function &rest path-filling-args) &body 
body Function 

Binds the local environment to apply a clipping region to the output of drawing 
functions in the body. The clipping region limits output from the drawing func- 
tions to points within the region. The shape of the clipping region is defined by a 
path-drawing function. 

stream The output stream. 

path-function A path-drawing function outlining the clipping region. 

The path can be arbitrarily complex, contain straight- and curved- 
line segments, and include more than one closed subpath. (For sev- 
eral examples of path functions: See the function graphicsrdraw- 
path.) 

graphics:with-clipping-from-output is a facility closely related to graphicsrwith- 

clipping-path. You use it to apply clipping regions defined by drawing functions, 
rather than by path-drawing functions as in the case of graphicsrwith-clipping- 
path. The following example shows the use of both facilities to achieve, in this 
case, the same graphic effect. 

;;; Star-shaped path drawer used by clipping-example 
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(defun star-drawer (xstandard-outputx) 

(graphics: set-current-position 0) 

(dotimes (i 4) 

(graphics:draw-l ine-to 1 0) 

(graphics: graphics-origin-to-cur rent-posit ion) 

(graphics:graphics-rotate (float (* -4/5 pi) 0.0))) 

(graphics: close-path)) 



This function draws four figures: 

1) a star 

2) a circle 

3) a circle clipped by a star-shaped path, 

demonstrating graphics:with-cl ipping-path, 

4) a star clipped by a circular path, 

demonstrating the closely related macro 
graphics :with-cl ipping-f rom-output. 



(defun clipping-example () 

(graphics:with-room-for-graphics (t 100) 

(graphics:with-graphics-translation (t 100 50) 
(graphics:with-graphics-scale (t 50) 

(graph i cs : draw-path #' star-drawer) ) ) 
(graphics:with-graphics-translation (t 200 50) 
(graphics:with-graphics-scale (t 50) 
(graphics:draw-ci rcle 1/2))) 
(graphics:with-graphics-translation (t 300 50) 
(graphics:with-graphics-scale (t 50) 

(graphics:with-cl ipping-path (t tf'star-drawer) 
(graphics:draw-ci rcle 1/2)))) 
(graphics:with-graphics-translation (t 400 50) 
(graphics:with-graphics-scale (t 50) 
(graphics: :with-cl ipping-f rom-output 
(t (graphics:draw-ci rcle 1/2)) 
(graph i cs : draw-path #' star-drawer) ) ) ) ) ) 

(cl ipping-example) 



• 



For an overview of graphics:with-clipping-path and related functions: See the sec- 
tion "Drawing Functions". 



graphics:with-coordinate-mode (stream mode) &body body 



Macro 
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Binds the local environment such that the figures produced within it are drawn 
with the specified coordinate mode. 

stream The output stream. 

mode Specifies the coordinate mode to be used, which is one of: 

rexact This is the default. Figures are drawn exactly 

according to the coordinates specified. Use this 
mode if it is important that figures tile correct- 
ly or if you require that shapes with fractional 
coordinates not be rounded to integer shapes. 

rinteger The coordinates specified to the drawing func- 

tion are rounded to integer values and special, 
faster integer drawing methods are used. Use 
this mode when speed is important in drawing a 
filled figure or one with thick lines and exact- 
ness is of little importance. 

reenter Figures are drawn so that they are centered 

around a whole pixel. For example, a circle with 
specified raduis r and center <x, y> would be 
drawn with actual center <x+1,jm-1> and radius 
r+1/2. Use this mode when you want small cir- 
cles to appear symmetrical about a single pixel 
and the circles need not align with other 
shapes. 

See the section "Scan Conversion". 



graphics:with-drawing-state (stream &rest args) &body body Macro 

Binds the local environment such that the drawing-state arguments in args are in 
effect during the execution of body with the output being sent to stream. These ar- 
guments can include any of the drawing keyword arguments other than the trans- 
form arguments. These are: 



:thickness :scale-dashes 




: scale-thickness 


:alu 


:line-end-shape 


rpattern 


:line-joint-shape 


: stipple 


rdashed :tile 




:dash-pattern:gray-level 




:initial-dash-phase 


rcolor 


:draw-partial-dashes 


ropaque 



Example: 
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(graphics :with-room-for-graphics (t 100) 

(graphics :with-drawing-state (t :thickness 4 :dashed t) 

(graphics:draw-rectangle 100 200 :filled nil) 

(graphics:draw-ci rcle 50 50 50 :filled nil))) 



! 



\ 



L-%..tt 



graphicsrwith-graphics-identity-transform (&optional stream) &body body 

Function 

Binds the local environment such that the graphics transformation matrix is the 
identity matrix. Graphics output from functions in the body is subject only to those 
coordinate system changes that are implemented by drawing-function keywords. 
(See the section "Keyword Options Affecting the Coordinate System".) 

stream The output stream. 

Examples: 

;;; Note that these will draw at the beginning of the window, because 
;;; the wi th-room-f or-graphi cs is defeated. 
(graphics:with-room-for-graphics (t 200) 
(graphics :with-graphics-transform 

(*standard-output* '(4 4 100 50)) 
(graph ics:with-graphics- identity- transform (t) 
(graphics:draw-rectangle 20 20 0)))) 

(graphics:with-room-for-graphics (t 200) 
(graphics :with-graphics-transform 

(*standard-output* '(4 4 100 50)) 
(graph ics:with-graphics- identity- transform (t) 
(graphics:draw-rectangle 20 20 

: transform 
'(4 4 100 50))))) 

For an overview of graphicsrwith-graphics-identity-transform and related func- 
tions: See the section "Coordinate System Facilities". 

graphicsrwith-graphics-rotation (stream theta) &body body Function 

Binds the local environment such that the graphics transformation matrix is modi- 
fied to rotate graphics output. (For an explanation of the graphics tranformation 
matrix: See the function graphicsrwith-graphics-transform.) 
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stream The output stream. 

theta A number specifying the rotation in radians. 

Example: 

(graphics :with-room-for-graphics (t 200) 

(graphics:with-graphics-translation (t 100 100) 
(graphics:with-graphics-rotation (t (* 1/3 pi)) 

(graphics: draw-rectangle -50 50 50 -50 :filled nil)) 
(graphics:draw-rectangle -50 50 50 -50 :filled nil))) 




For an overview of graphicsrwith-graphics-rotation and related functions: See the 
section "Coordinate System Facilities". Also: See the section "Keyword Options Af- 
fecting the Coordinate System". 



graphics:with-graphics-scale {stream scale &optional (y-scale graphics::scale)) 

&body body Function 

Binds the local environment such that the graphics transformation matrix is modi- 
fied to apply a scaling factor to graphics output. (For an explanation of the graph- 
ics tranformation matrix: See the function graphicsrwith-graphics-transform.) 

stream The output stream. 

scale A number specifying the scaling factor. 

y-scale A number specifying the y scaling factor (if different from scale). 

Example: 

(graphics :with-room-for-graphics (t 100) 
(graphics:with-graphics-scale (t 5) 

(graphics:draw-rectangle 10 10 20 20)) 
(graphics:draw-rectangle 10 10 20 20 :gray-level 



.5)) 
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For an overview of graphics:with-graphics-scale and related functions: See the 
section "Coordinate System Facilities". Also: See the section "Keyword Options Af- 
fecting the Coordinate System". 



graphicsrwith-graphics-subroutine f&optional (stream '*standard-output*J &rest 
special-variable-arguments) &body body Function 

Improves the density of binary encoding. 

stream The graphic output stream 

special-variable-arguments Arguments for special variables accessed 

within body. 

graphicsrwith-graphics-transform {stream transform) &body body Function 

Binds the local environment such that the graphics transformation matrix is com- 
posed with transform. 

stream The output stream. 

transform Specifies a list of six elements in the graphics transformation ma- 
trix applied to the local coordinate system used for a drawing func- 
tion. The element order is a, b, c, d, e, and f (see below). 

Arbitrary transformation of coordinates is effected by multiplication 
of coordinate vectors by a transformation matrix. For coordinates in 
two-dimensional space, a 3 x 3 transformation matrix is used, 



e f 1 

of which the elements in the third column are constant. Thus, six 
elements, effectively control the transformation as follows: 

• Scaling in the x and y dimensions is controlled by elements a 
and d, respectively. Values of 1 for these elements result in no 
scaling. 
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• Translation in the x and y dimensions is controlled by elements 
e and f, respectively. Values of for these elements result in no 
translation. 

• Rotation about the origin is controlled by elements a, b, c, and 
d. Counterclockwise rotation by an angle a is effected by a = 
cosa, b = since, c = -since, and d = cosoc. A value of for b and c 
results in no rotation (oc = 0). 

Example: 

; This example scales the size of the rectangle by a 
; factor of 4 and translates its position by 100 in 
; the x direction and 50 in the y direction. 

(graphics:with-room-for-graphics (t 200) 

(graphics :with-graphics-transform (t '(4004 100 50)) 
(graphics:draw-rectangle 20 20 0))) 

For an overview of graphicsrwith-graphics-transform and related functions: See 
the section "Coordinate System Facilities". Also: See the section "Keyword Options 
Affecting the Coordinate System". 



graphicsrwith-graphics-translation {stream delta-x delta-y) &body body Function 

Binds the local environment such that the graphics transformation matrix is modi- 
fied to offset the origin of the graphics coordinate system. (For an explanation of 
the graphics tranformation matrix: See the function graphicsrwith-graphics- 
transform.) 

stream The output stream. 

delta-x A number specifying the x offset. 

delta-y A number specifying the y offset. 

Example: 

(graphics:with-room-for-graphics (t 100) 

(graphics:with-graphics-translation (t 40 40) 

(graphics:draw-rectangle 40 40 0)) 
(graphics:draw-rectangle 40 40 :filled nil)) 



For an overview of graphicsrwith-graphics-translation and related functions: See 
the section "Coordinate System Facilities". Also: See the section "Keyword Options 
Affecting the Coordinate System". 
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graphics:with-output-as-graphics-presentation (&optional stream &rest args) 
&body body Function 

Binds the local environment such that graphics output generated in the body is re- 
turned as a presentation. 

stream The output stream. 

This macro is the graphics equivalent of dw:with-output-as-presentation (on 
which it is based). It is useful with functions for manipulating graphics presenta- 
tions, namely, graphicsrerase-graphics-presentation and graphicsrreplacing- 
graphics-presentation. The following example shows the use of all three facilities: 

(defun replacing-example () 

(graphics :with-room-for-graphics (t 200) 
(let (poly) 

(setq poly (graphics:with-output-as-graphics-presentation () 
(graph i cs : draw-pol ygon 

'(100 10 350 10 350 100 225 150 100 100 100 10) 
: filled t 
: gray-level .25 
:convex-p t))) 
(sleep 1) 

(setq poly (graphics: replacing-graphics-presentation (t poly) 
(graphics: draw-pol ygon 

'(100 10 350 10 350 100 225 150 100 100 100 10) 
: filled t 
: gray-level 1 
:convex-p t))) 
(sleep 1) 

(graph i cs : erase-graphi cs-presentati on pol y) ) ) ) 
(repl aci ng-exampl e) 

For an overview of graphics:with-output-as-graphics-presentation and related 
functions: See the section "Other Basic Facilities for Graphic Output". 



tv:bitmap-stream-copy-bitmap stream Function 

Makes a copy of the bitmap or raster associated with a stream and returns five 
values: 

• The bitmap 

• Left top 

• Right top 

• Left bottom 
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Right bottom 



tv:with-output-to-bitmap f&optional stream &key :for-stream .-graphics-transform) 
&body body Function 

stream The stream to which to return the bitmap. 

:for-stream The stream for which the bitmap is intended. 

rgraphics-transform An optional transform to be applied. 

Returns a raster array and positions containing the image output by body. 

(defun bitmap-example (&optional (stream xstandard-outputx)) 
(graphics: with- room-for-graphics () 

(graphics:draw-triangle 200 50 50 

:tile (tv:with-output-to- bitmap (bstream 
:for-stream stream) 
(graphics :draw-ci rcle 10 

: gray-level .25 : stream bstream) 
(graphics:draw-regular-polygon 8 16 6 
: gray-level .75 
: stream bstream))))) 



tv:with-output-to-bitmap-stream (bitmap-stream &rest args &key (for-stream nil) 
&allow-other-keys) &body body Function 

bitmap-stream A stream that is a raster array intended to hold the 

image generated by body. 

args :for-stream, the stream for which the bitmap is intended, and, op- 

tionally, rgraphics-transform, an optional transform to be applied. 

Binds bitmap-stream to a specially allocated stream that accepts the graphic output 
during execution of body. At any time, the :bitmap-and-edges message to this 
stream returns the current image. 



graphicsrwith-physical-device-scale (stream scale unit) &body body Macro 

Scales the output produced by body on stream so that it really is the size specified 
on the output device used, scale is a number and unit is one of rinch, rcentimeter, 
or :mica. 

Note that a scale factor is applied that assumes that the current scale is 1. There- 
fore, you can still zoom a picture drawn using this by surrounding it with a 
graphicsrwith-graphics-scale. 
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(graphics: with- room-for-graphics () 
(graphics :with-physical -device-scale (t 1 :centimeter) 
(graphics :draw-ci rcle 1 1/2 1/2))) 



graphics:with-room-for-graphics (&optional stream height) &body body Function 

Binds the local environment to establish a Cartesian coordinate system for doing 
graphics output. The origin <0, 0> of the local coordinate system is in the lower 
left corner of the area created. After graphic output is completed, the cursor is po- 
sitioned past (immediately below) this origin. The bottom of the vertical block allo- 
cated is at this location - that is, just below point <0, 0> - not necessarily at the 
bottom of the output done. If your drawing extends in the negative y direction, 
then you should use graphicsrwith-graphics-translation to position it within the 
allocated space. This works for the screen, the lgp2, and the lgp3, even though 
their coordinate systems are really not the same. 

stream The output stream. If this argument is t or not supplied, it defaults 
to *standard-output*. 

height A number specifying the vertical space, in pixels, created for graph- 
ics output. If this argument is not supplied, the height is computed 
from the height of the output to be done. 

Example: 

;;; Try evaluating the following forms. Note the orientation 
;;; of the lines drawn and the position of the cursor when done. 

(multiple-value-bind (x1 y1 x2 y2) 

(send xstandard-outputx : visible-cursorpos-1 imits) 
(ignore x1 x2 y2) 
(graphics:draw-line (+ y1) 200 (+ 200 y1))) 

(graphics:with-room-for-graphics (t 200) 
(graphics:draw-line 200 200)) 

(graphics:with-room-for-graphics (t 200) 
(graphics:draw-line 200 -200)) 

(graphics:with-room-for-graphics (t 200) 

(graphics:with-graphics-translation (t 200) 
(graphics:draw-line 200 -200))) 

For an overview of graphics:with-room-for-graphics and related functions: See 
the section "Coordinate System Facilities". 



graphics:write-encoded-graphics-as-characters array stream Function 
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Translates each element of array into a character, possibly preceded by a code 
character, and writes the result to stream. See the section "Other Advanced Facili- 
ties for Graphic Output". 

array An array with elements of type (unsigned-byte 8) produced by the 
function graphics:binary-encode-graphics-to-array, which contains 
the encoded version of a graphics function. 

stream Any output stream. 
Standard Keyword Options to Drawing Functions 

rstream Option 

Specifies the output stream for a drawing function; the default is *standard- 
output*. 

:alu Option 

Specifies the drawing mode for a drawing function. Possible values for this 
option are: 

:draw Pixels specified by the drawing function are turned on, regardless 
of whether some of the pixels were already on. This is the default 
drawing mode. 

rerase Pixels specified by the drawing function are turned off, regardless 
of whether some of the pixels were already off. 

:flip Pixels specified by the drawing function are turned on if they were 

previously off, and off if they were previously on. 

Additionally, numeric and color-extended alu operations are valid values for 
this option. Whether "on" means white or black depends on the whether or 
not the display window is in inverse video mode: if inverse video is not in ef- 
fect, on means white. 



rstipple Option 

Specifies a two-dimensional one-bit array. In normal, :alu :draw, mode, a 1 in 
the array specifies that the corresponding pixel is on; 0, off. The origin of the 
array is aligned with the coordinate origin of the output display. 

Predefined stipple patterns are in graphics:*stipple-arrays*. 

You can create your own stipple patterns using the Stipple Editor which, if it 
is loaded, is invoked by pressing SELECT | . You can also generate a stipple 
pattern by using the tv:with-output-to-bitmap macro. 



1595 Keyword Options to Drawing Functions 



:tile Option 

Specifies a two-dimensional array of n-bit values. The n bits of each entry in 
the array specify the color of the corresponding pixel. The origin of the array 
is aligned with the coordinate origin of the output display. You can also gen- 
erate a tiling pattern by using the tv:with-output-to-bitmap macro. 



rcolor Option 

Specifies a color to be used for output on a device that supports color. On de- 
vices that do not support color, a gray-level pattern appropriate to the intensi- 
ty of the specified color is displayed instead. The possible choices are: rblack, 
:red, rgreen, :blue, :cyan, ryellow, rmagenta, and rwhite. 



rfilled Option 

Boolean option specifying whether all pixels within the figure created by a 
drawing function are turned on, or only the outline pixels; the default is t 
(filled). 



rpattern Option 

Specifies a pattern to be drawn within the figure created by a drawing func- 
tion, rpattern is the most general control of the "looks" of thie inside of a 
filled shape. The default is nil. The rpattern drawing option can be a(n) 

• stipple This is identical to rstipple <value>. 

• color This is identical to rcolor <value>. 

• instance The case of interest here. 

Several functions are provided for making instances to pass as the pattern. 
See the function graphicsrmake-simple-pattern. See the function 
graphicsrmake-two-color-stipple. See the function graphicsrmake- 
contrasting-pattern. See the function graphicsrmake-device-conditional- 

pattern. Additionally, there are three layered protocols for implementing 
one's own instances to be passed as rpattern. See the section "Texturing". 
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(defun pattern-examplel () 

(graphics :with-room-for-graphics (t 200) 
(let ((bitmap (tv: make-binary-gray 8 8 



The picture of 
what you want 
the bit pattern 
displayed to 
look like, in 
this case the 
number 1 . 



'(#b00000000 
#b00001000 
#b00111000 
#b00001000 
#b00001000 
#b00001000 
#b00001000 
#b00111110)))) 
(graphics:draw-ci rcle 200 100 50 

: pattern bitmap)))) 

(defun pattern-example2 () 

(let ((bitmap (tv:with-output-to-bitmap (t) 
(graphics: draw-string 
"symbolics" 
: character-style 

'(:swiss :bold-italic :large))))) 
(graphics:with-room-for-graphics (t 250) 

(graphics:draw-triangle 100 25 400 25 250 250 

: pattern bitmap)))) 
(pattern-exampl e1 ) 
(pattern-exampl e2) 



:gray-level Option 

Specifies the black-to-white level of the graphic as a ratio or decimal fraction 
between and 1; the default value is 1. On 1-bit devices, gray levels are sim- 
ulated by stippling. 



Example: 
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(defun gray-level -example () 

(graphics :with-room-for-graphics (t 200) 
(graph i cs : draw-pol ygon 

'(100 10 350 10 350 100 225 150 100 100 100 10) 
: gray-level 1/4 
:convex-p t) 
(graphics: draw-pol ygon 

'(100 10 350 10 350 100 225 150 100 100 100 10) 
:filled nil 
:convex-p t) 
(graphics: draw-pol ygon 

'(259 137 259 165 289 165 289 124 259 137) 
: gray-level 3/4 
:convex-p t) 
(graphics:draw-rectangle 200 70 250 10 

: gray-level 1/2 
: opaque t) 
(graphics:draw-rectangle 200 70 250 10 

:filled nil) 
(graphics:draw-rectangle 135 90 175 40 

: gray-level 1/20 
: opaque t) 
(graphics:draw-rectangle 135 90 175 40 

:filled nil) 
(graphics:draw-l ine 135 65 175 65) 
(graphics:draw-rectangle 275 90 315 40 

: gray-level 1/20 
: opaque t) 
(graphics:draw-rectangle 275 90 315 40 

:filled nil) 
(graphics:draw-l ine 275 65 315 65))) 

(gray-1 evel -exampl e) 




ropaque 



Option 
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Boolean option specifying whether pixels in the source pattern of a drawing 
function are cleared (before the graphic is output) or left alone; the default is 
t. ropaque t means draw pixels that are off in the background color. The re- 
sult of ropaque t is not influenced by the :alu supplied for the pixels that are 
on. If you draw something over an existing figure using ropaque t :alu :flip, 
the pixels that were originally on are inverted, and pixels that were originally 
off are cleared (set to the background color). 

To see the effect of this option, try calling the following function with t and 
then nil. 

(defun opaque-example (t-or-nil) 

(graphics :with-room-for-graphics (t 200) 
(graphics :draw-ci rcle 200 100 50 

: pattern tv: 75%-gray) 
(graphics:draw-triangle 165 65 235 65 200 150 

: pattern tv:25%-gray 
: opaque t-or-nil))) 

(opaque-example t) 



(opaque-example nil) 




rthickness Option 

Specifies the thickness, in pixels, of the line or lines drawn by a drawing 
function. The default is device-dependent: for the screen, it is 0, which speci- 
fies the minimum thickness for that device; for the lgp2 and lgp3, it is 1. The 
thinnest possible thickness is 0, which also specifies that the line is to be po- 
sitioned roughly. For accurate positioning, specify a thickness of 1. 

This option is not operable if the function draws a filled (: filled t) figure. 
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(graphics :with-room-for-graphics (t 100) 

(graphics: draw-triangle 50 25 25 :filled nil :thickness 2) 

(graphics: draw-triangle 100 150 125 25 :filled nil :thickness 4) 

(graphics:draw-triangle 200 250 225 25 :filled nil :thickness 8)) 



Z\ z± 




: scale-thickness 



Option 



Boolean option specifying whether to scale thickness, as well as other linear 
dimensions, when a scaling factor is specified (via the rscale keyword to a 
drawing function: See the option rscale.). The default is nil. 

This option is not operable if the function draws a filled (: filled t) figure. 

(graphics:with-room-for-graphics (t 100) 
(graphics:with-graphics-translation (t 100 50) 
(graphics: draw- rectangle 
(graphics: draw- rectangle 
(graphics: draw- rectangle 

:scale-thickness nil))) 






-10 


10 


10 


filled nil 


thickness 1) 





-10 


10 


10 


filled nil 


thickness 1 :scale 2) 





-10 


10 


10 


filled nil 


thickness 1 :scale 4 





□ 





: dashed 



Option 



Boolean option specifying whether lines are drawn as a series of dashes by a 
drawing function; the default is nil. 

This option is not operable if the function draws a filled (: filled t) figure. 

(graphics:with-room-for-graphics (t 100) 
(graphics:draw-rectangle 100 100 :filled nil :dashed t)) 



rdash-pattern 



Option 
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Specifies a sequence, usually a vector, controlling the dash pattern of a draw- 
ing function. If no pattern is specified, the default dashes are 10 pixels long 
and separated by spaces of 10 pixels. The vector must contain an even num- 
ber of elements or you will get an error. 

The following example draws a line as a series of dashes, alternating in 
length between 16 and 8 pixels, with intervening spaces of 4 pixels. Note that 
these lengths result from applying a scaling factor of 4, implemented by the 
rscale and rscale-dashes keywords. 

(graphics :with-room-for-graphics (t 200) 
(graphics :draw-l ine 25 25 100 25 

: dashed t : scale 4 
scale-thickness nil 
scale-dashes t 
dash-pattern #(4 1 2 1))) 



This option is not operable if the rdashed option is nil. 



rscale-dashes Option 

Boolean option specifying whether to scale dashes when the rdashed option to 
a drawing function is t and a scaling factor is specified (via the rscale key- 
word: See the option rscale.). The default is nil. 

For an example: See the option rdash-pattern. 

This option is not operable if the rdashed option is nil. 



rinitial-dash-phase Option 

Specifies the offset, in pixels, of the start of the first dash from the starting 
point of the line; the default value is 0. 

This option is not operable if the rdashed option to the drawing function is 
nil. 



rdraw-partial-dashes Option 

Boolean option specifying whether a partial dash is drawn at the end of a 
dashed line so that it reaches its specified end-point. The default is t: dashes 
are drawn with the specified numbers of pixels on and off until the endpoint 
is reached, at which point drawing stops wherever in the pattern you happen 
to be. 
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If you specify nil for this option, the drawing routine will adjust the spacing 
of the dashes so that the lines ends on a "dash." In the simple case — that 
is, with only a single pair of numbers in the dash pattern — a dash is a solid 
line of (on) pixels, so both ends of such a line are drawn. For example, try 
these: 

(graphics :with-room-for-graphics (t 10) 

(graphics :draw-l ine 3 200 3 :dashed t : dash-pattern #(20 15) 

: draw-partial -dashes t) 
(graphics:draw-l ine -3 200 -3 :dashed t 

:dash-pattern #(20 15) : draw-partial -dashes nil) 
(graphics:draw-line 200 -3 200 3)) 



(graphics:with-room-for-graphics (t 250) 
(let ((zoom 5)) 

(doli st (partial ' (t nil)) 

(graphics:with-graphics-translation (t (if partial (* 25 zoom) 0)) 
(dotimes (i 20) 

(let ((y (* (- 19 i) zoom))) 

(graphics:draw-l ine y (* i 4 zoom) y 
: dashed T 

:dash-pattern #(20 15) 
: draw-partial -dashes partial) 
(graphics:draw-l ine (- y 1) (* i 4 zoom) (- y 1)))))))) 

For more complicated dash patterns, a dash is considered to be a solid line 
somewhere in the pattern: you will have to experiment to determine the exact 
result of using the option. 

This option is not operable if the rdashed option to the drawing function is 
nil. 

Some hardcopy devices, most notably PostScript printers, cannot adjust the 
spacing of the dashes; that is, they will draw partial dashes even if you speci- 
fy :draw-partial-dashes nil. 



:line-end-shape Option 

Specifies the shape for the ends of lines drawn by a drawing function, one of 
:butt, rsquare, rround, or :no-end-point; the default is :butt. 

To see the differences among end shapes, try evaluating the following: 
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(graphics :with-room-for-graphics (t 200) 
(graphics: draw-line 200 40 200 140 

: 1 ine-end-shape :butt 

:thickness 20) 
(graphics:draw-line 240 40 240 140 

: 1 ine-end-shape :no-end-point 

:thickness 20) 
(graphics:draw-line 280 40 280 140 

: 1 ine-end-shape : square 

:thickness 20) 
(graphics:draw-line 320 40 320 140 

: 1 ine-end-shape : round 

:thickness 20) 
(graphics:draw-line 190 30 330 30) 
(graphics:draw-line 190 150 330 150)) 

The vertical lines on the left have rbutted ends; they do not extend beyond 
the y-coordinates (40 and 140) given for the line. The lines on the right have 
rsquared and rrounded ends. These lines extend, because of the rthickness 
parameter (20), 10 pixels above and below the top and bottom line coordinates. 

This option is not operable if the function draws a filled (: filled t) figure. 



:line-joint-shape Option 

Specifies the shape of joints between line segments of closed, unfilled figures, 
when the rthickness option to a drawing function is greater than 1. The pos- 
sible shapes are rmiter, rbevel, rround, and rnone; the default is rmiter. 

The following example draws four pentagons illustrating the differences 
among, from left to right, the rmiter, rbevel, rround, and rnone joint shapes: 
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(graphics :with-room-for-graphics (t 200) 

(graphics: draw-regular-polygon 40 40 100 40 5 

:filled nil 
:thickness 15 
: 1 ine-joint-shape :miter) 

(graphics:draw-regular-polygon 190 40 250 40 5 

:filled nil 
:thickness 15 
: 1 ine-joint-shape :bevel) 

(graphics:draw-regular-polygon 340 40 400 40 5 

:filled nil 
:thickness 15 
: 1 ine-joint-shape : round) 

(graphics:draw-regular-polygon 490 40 550 40 5 

:filled nil 
thickness 15 
line-joint-shape :none)) 



oooo 



This option is not operable if the function draws a filled (: filled t) figure. 

Some hardcopy devices may not support all line joint shapes. Notably, 
PostScript printers treat :none as rbevel. 



:mask 



Option 



Specifies a bitmap of points affected by the drawing operation; the default is 
nil, that is, no bitmap. 

Use this option to mask out portions of the output graphic that you do not 
want displayed. For example, the following form outputs a rectangle, but does 
so through a triangular mask, so that only a triangle gets displayed: 

(graphics:with-room-for-graphics (t 200) 
(multiple-value-bind (bitmap x y) 

(graphics :with-output-to-bitmap () 

(graphics:draw-triangle 100 50 200 150 300 50)) 
(graphics:draw-rectangle 200 400 

: gray-level .33 

:mask bitmap :mask-x x :mask-y (+ 100 y)))) 
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:mask-x Option 

Specifies the x-coordinate, with respect to the local graphics origin, of the 
lower lefthand corner of the position of the rectangular bitmap region speci- 
fied by the :mask option. 



:mask-y Option 

Specifies the y-coordinate, with respect to the local graphics origin, of the 
lower lefthand corner of the position of the rectangular bitmap region speci- 
fied by the :mask option. 



rreturn-presentation Option 

Boolean option specifying whether a drawing function should return the newly 
created graphic as a presentation object; the default is nil. 

Use this option when you wish to manipulate the output of a single drawing 
function as a presentation. If you want to manipulate the collective output of 
a series of drawing functions as a single presentation, use the graphicsrwith- 
output-as-graphics-presentation macro instead. 

Some facilities are provided for handling graphic presentations, in particular, 
graphicsrerase-graphics-presentation and graphicsrreplacing-graphics- 
presentation. The following example uses the former in conjunction with the 
rreturn-presentation keyword: 
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(graphics :with-room-for-graphics (t 100) 
(graphics :with-graphics-scale (t 50) 
(let ((presentations 
(list 
(graphics: draw-regular-polygon .75 .5 1.25 .5 4 
: gray-level .25 : return-presentation t) 
(graphics: draw-regular-polygon .25 1.25 3 

: gray-level .75 : return-presentation t) 
(graphics:draw-el 1 ipse 1.5 .5 .4 .4 

: gray-level .5 : return-presentation t)))) 
(sleep 2) 
(graphics:erase-graphics-presentation (first presentations))))) 



Coordinate-System Keyword Options 



rrotation Option 

Specifies the rotation of the graphic in plus or minus radians; the default is 
0. The axis of rotation is the local origin (0, 0). 

In the following example, the origin is first established at the lower, left 
corner of the graphic display area created by graphics:with-room-for- 
graphics, then translated 300 pixels to the right and 15 pixels up by the 
graphicsrwith-graphics-translation macro. In this coordinate system, the ar- 
row is rotated counter-clockwise about the origin at an offset of 10 pixels. 
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(defun rotating-arrow () 

(graphics :with-room-for-graphics (t 225) 

(graphics:with-graphics-translation (t 300 15) 

(graphics: draw-arrow 10 200 

:thickness 5) 

(sleep .2) 

(graphics:draw-arrow 10 200 

:thickness 5 

: rotation (* pi . 125)) 

(sleep .2) 

(graphics:draw-arrow 10 200 

:thickness 5 

: rotation (* pi .25)) 

(sleep .2) 

(graphics:draw-arrow 10 200 

:thickness 5 

: rotation (* pi .375)) 

(sleep .2) 

(graphics:draw-arrow 10 200 

:thickness 5 

: rotation (* pi .5)) 

(sleep .2) 

(graphics:draw-arrow 10 200 

:thickness 5 

: rotation (* pi .625)) 

(sleep .2) 

(graphics:draw-arrow 10 200 

:thickness 5 

: rotation (* pi . 75)) 

(sleep .2) 

(graphics:draw-arrow 10 200 

:thickness 5 

: rotation (* pi .875)) 

(sleep .2) 

(graphics:draw-arrow 10 200 

:thickness 5 

: rotation pi)))) 

(rotating-arrow) 



rscale Option 

Specifies a number applied as a scaling factor to the x and y parameters of a 
drawing function; the default is 1. 

rscale does not affect the line thickness parameter. To do so, use the rscale- 
thickness keyword. 
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(graphics :with-room-for-graphics (t 100) 
(graphics :draw-ci rcle 1 1 1 :scale 20)) 





:scale-x Option 

Specifies a number applied as a scaling factor to the x parameters of a draw- 
ing function; the default is 1. 

(graphics :with-room-for-graphics (t 100) 



(graphics :draw-ci rcle 50 50 20 :scale-x 4)) 



:scale-y Option 

Specifies a number applied as a scaling factor to the y parameters of a draw- 
ing function; the default is 1. 

(graphics :with-room-for-graphics (t 100) 
(graphics:draw-circle 100 100 50 :scale-y 1/2)) 



rtransform Option 

Specifies a list of six elements in the graphics transformation matrix applied 
to the local coordinate system used for a drawing function. The element order 
is a, b, c, d, x, and y (see below). The default is nil, resulting in no transfor- 
mation. 

Arbitrary transformation of coordinates is effected by multiplication of coordi- 
nate vectors by a transformation matrix. For coordinates in two-dimensional 
space, a 3 x 3 transformation matrix is used, 



x y 1 

of which the elements in the third column are constant. Thus, six elements, 
effectively control the transformation as follows: 

• Scaling in the x and y dimensions is controlled by elements a and d, re- 
spectively. Values of 1 for these elements result in no scaling. 
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• Translation in the x and y dimensions is controlled by elements x and y, 
respectively. Values of for these elements result in no translation. 

• Rotation about the origin is controlled by elements a, b, c, and d. Counter- 
clockwise rotation by an angle a is effected by a = cosa, b = since, c = - 
since, and d = cosa. A value of for b and c results in no rotation (a = 0). 

Example: 

This example scales the size of the rectangle by a 
factor of 4 and translates its position by 100 in 
the x direction and 50 in the y direction. 

(graphics:with-room-for-graphics (t 200) 
(graphics:draw-rectangle 20 20 

:transform '(4 4 100 50))) 



rtranslation Option 

Specifies x and y offsets relative to the local origin (0, 0) used for a drawing 
function. The offsets are specified as a list, (x y) . The offset units depend on 
the output device; if it is the terminal screen, the units are pixels. 

Using this option has the effect of moving the local origin to the new position 
specified by x and y. The default is nil, no translation. 

;;; Contrast this with giving 50 50 as the center, which would have caused it to 
; ; ; be rotated. 

(graphics:with-room-for-graphics (t 100) 
(graphics:draw-el 1 ipse 40 20 :translation '(50 50) :rotation (/ pi 4))) 







